{"id":13527427,"url":"https://github.com/openzipkin/zipkin-js","last_synced_at":"2025-05-14T21:07:19.243Z","repository":{"id":54254609,"uuid":"58535548","full_name":"openzipkin/zipkin-js","owner":"openzipkin","description":"Zipkin instrumentation for Node.js and browsers","archived":false,"fork":false,"pushed_at":"2024-02-09T01:03:31.000Z","size":2863,"stargazers_count":570,"open_issues_count":76,"forks_count":174,"subscribers_count":33,"default_branch":"master","last_synced_at":"2025-05-01T03:03:42.969Z","etag":null,"topics":["distributed-tracing","hacktoberfest","javascript","nodejs","openzipkin","tracing","zipkin"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/openzipkin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-05-11T10:28:12.000Z","updated_at":"2025-04-24T09:50:28.000Z","dependencies_parsed_at":"2024-02-09T02:23:07.795Z","dependency_job_id":"a1970861-5567-41ce-ab6b-39c699fb05b4","html_url":"https://github.com/openzipkin/zipkin-js","commit_stats":{"total_commits":500,"total_committers":97,"mean_commits":5.154639175257732,"dds":0.862,"last_synced_commit":"ec89188cf6a07e184ab886c1dfb6c9dc276ddfa4"},"previous_names":[],"tags_count":58,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openzipkin%2Fzipkin-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openzipkin%2Fzipkin-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openzipkin%2Fzipkin-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openzipkin%2Fzipkin-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/openzipkin","download_url":"https://codeload.github.com/openzipkin/zipkin-js/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252293085,"owners_count":21724960,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["distributed-tracing","hacktoberfest","javascript","nodejs","openzipkin","tracing","zipkin"],"created_at":"2024-08-01T06:01:47.763Z","updated_at":"2025-05-14T21:07:14.228Z","avatar_url":"https://github.com/openzipkin.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# Zipkin JS\n\n[![Build Status](https://travis-ci.org/openzipkin/zipkin-js.svg?branch=master)](https://travis-ci.org/openzipkin/zipkin-js)\n[![npm version](https://badge.fury.io/js/zipkin.svg)](https://badge.fury.io/js/zipkin)\n![npm](https://img.shields.io/npm/dm/zipkin.svg)\n[![Gitter chat](https://badges.gitter.im/openzipkin/zipkin.svg)](https://gitter.im/openzipkin/zipkin?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n\nThis is a set of libraries for instrumenting Node.js and browser applications. The `zipkin` library can be run in both Node.js and the browser.\n\nIf you'd like to try this out right away, try our [example app](https://github.com/openzipkin/zipkin-js-example) which shows\nhow tracing services looks.\n\n## Installation\n\n```bash\nnpm install zipkin --save\n```\n\n## Basic Setup\n\n```javascript\nconst {\n  Tracer,\n  BatchRecorder,\n  jsonEncoder: {JSON_V2}\n} = require('zipkin');\nconst CLSContext = require('zipkin-context-cls');\nconst {HttpLogger} = require('zipkin-transport-http');\n\n// Setup the tracer\nconst tracer = new Tracer({\n  ctxImpl: new CLSContext('zipkin'), // implicit in-process context\n  recorder: new BatchRecorder({\n    logger: new HttpLogger({\n      endpoint: 'http://localhost:9411/api/v2/spans',\n      jsonEncoder: JSON_V2\n    })\n  }), // batched http recorder\n  localServiceName: 'service-a' // name of this application\n});\n\n// now use tracer to construct instrumentation! For example, fetch\nconst wrapFetch = require('zipkin-instrumentation-fetch');\n\nconst remoteServiceName = 'youtube'; // name of the application that\n                                     // will be called (optional)\nconst zipkinFetch = wrapFetch(fetch, {tracer, remoteServiceName});\n```\n\n## Browser\n\nThe `zipkin` library can be used in the browser. The `web` [example](https://github.com/openzipkin/zipkin-js-example) shows an example of a browser based application making a call to a backend server with trace headers attached.\n\n### Instrumentation\n\nThe following libraries can be instrumented in the browser:\n\n- [fetch](packages/zipkin-instrumentation-fetch) (zipkin-instrumentation-fetch)\n\n### Transports\n\nThe following transport is available for use in the browser:\n\n- [http](packages/zipkin-transport-http)\n\nFor debugging purposes, you can also use the `ConsoleRecorder`:\n\n```javascript\nconst tracer = new Tracer({\n  ctxImpl: new ExplicitContext(),\n  recorder: new ConsoleRecorder(),\n  localServiceName: 'service-a' // name of this application\n});\n```\n\n### Typescript\n\nSince some of the `zipkin-js` libraries are used in both the browser and Node.js runtimes, some Typescript may complain about missing dependencies when attempting to compile with these libraries for the browser. For instance, the `zipkin-transport-http` library will determine at runtime whether to use the `window.fetch` API instead of `node-fetch` but the compiler will attempt to resolve `node-fetch`. As a workaround, you can stub the libraries since they are not used in your `tsconfig.json` (this assumes you added the `empty` module to your `package.json` but any library could be used):\n\n```json\n{\n  \"compilerOptions\": {\n    \"baseUrl\": \".\",\n    \"paths\": {\n      \"node-fetch\": [\n        \"node_modules/empty/index.js\"\n      ],\n      \"os\": [\n        \"node_modules/empty/index.js\"\n      ],\n    }\n  }\n}\n```\n\n## Node.js\n\nThe following libraries are specific to Node.js. Node.js version 8.x and later are supported:\n\n- zipkin-context-cls\n- zipkin-encoder-thrift\n\n### Instrumentations\n\nVarious Node.js libraries have been instrumented with Zipkin support.\nEvery instrumentation has an npm package called `zipkin-instrumentation-*`.\n\nAt the time of writing, zipkin-js instruments these libraries:\n\n- [cujojs/rest](packages/zipkin-instrumentation-cujojs-rest) (zipkin-instrumentation-cujojs-rest)\n- [express](packages/zipkin-instrumentation-express) (zipkin-instrumentation-express)\n- [fetch](packages/zipkin-instrumentation-fetch) (zipkin-instrumentation-fetch)\n- [got](packages/zipkin-instrumentation-gotjs) (zipkin-instrumentation-gotjs)\n- [hapi](packages/zipkin-instrumentation-hapi) (zipkin-instrumentation-hapi)\n- [memcached](packages/zipkin-instrumentation-memcached) (zipkin-instrumentation-memcached)\n- [redis](packages/zipkin-instrumentation-redis) (zipkin-instrumentation-redis)\n- [restify](packages/zipkin-instrumentation-restify) (zipkin-instrumentation-restify)\n- [postgres](packages/zipkin-instrumentation-postgres) (zipkin-instrumentation-postgres)\n- [request](packages/zipkin-instrumentation-request) (zipkin-instrumentation-request)\n- [request-promise](packages/zipkin-instrumentation-request-promise) (zipkin-instrumentation-request-promise)\n- [connect](packages/zipkin-instrumentation-connect) (zipkin-instrumentation-connect)\n- [superagent](packages/zipkin-instrumentation-superagent) (zipkin-instrumentation-superagent)\n- [grpc-client](packages/zipkin-instrumentation-grpc-client) (zipkin-instrumentation-grpc-client)\n- [axios](packages/zipkin-instrumentation-axiosjs) (zipkin-instrumentation-axiosjs)\n- [KafkaJS](packages/zipkin-instrumentation-kafkajs) (zipkin-instrumentation-kafkajs)\n- [koa](packages/zipkin-instrumentation-koa) (zipkin-instrumentation-koa)\n\nEvery module has a README.md file that describes how to use it.\n\n### Transports\n\nYou can choose between multiple transports; they are npm packages called `zipkin-transport-*`.\n\nCurrently, the following transports are available:\n\n- [http](packages/zipkin-transport-http)\n- [kafka](packages/zipkin-transport-kafka)\n- [scribe](packages/zipkin-transport-scribe)\n- [aws-sqs](packages/zipkin-transport-aws-sqs)\n\nEvery package has its own README.md which describes how to use it.\n\n## Clock precision\n\nZipkin timestamps are microsecond, not millisecond granularity. When running in **node.js**,\n[process.hrtime](https://nodejs.org/api/process.html#process_process_hrtime_time) is used to\nachieve this.\n\nIn **browsers**, microsecond precision requires installing a shim like [browser-process-hrtime](https://github.com/kumavis/browser-process-hrtime):\n\n```javascript\n// use higher-precision time than milliseconds\nprocess.hrtime = require('browser-process-hrtime');\n```\n\n## Developing\n\nThe code base is a monorepo. We use [Lerna](https://lernajs.io/) for managing inter-module\ndependencies, which makes it easier to develop coordinated changes between the modules.\nInstead of running lerna directly, the commands are wrapped with npm; `npm run lerna-publish`.\n\nTo setup the development environment, run:\n\n```\nyarn\n```\n\n### Running all tests: `yarn test`\n\n- Note that the memcached, redis and postgres integration tests requires you to have local instances running.\n- The Kafka transport integration test will start an embedded Kafka server for the test, which requires you to have\nJava installed on your machine.\n- The KafkaJS instrumentation tests require `docker` and `docker-compose` and will start up a containerized Kafka\ninstance to run against. Its NPM script uses commands that require a recent version of bash.\n\n### Running tests for one module `npm run lerna-test -- --scope zipkin-instrumentation-foo`\n\nRunning yarn will execute all tests, which can be distracting if you are only attempting to change one module.\nKnowing that tests are managed with lerna underneath, you can use the `--scope` parameter to constrain what's run.\n\nEx. to only run integration tests for postgres\n```bash\nnpm run lerna-test -- --scope zipkin-instrumentation-postgres\n```\n\nEx. to only run a single integration test in the zipkin package\n```bash\nnpm run lerna-test -- --scope zipkin -- test/batch-recorder.integrationTest.js\n```\n\n### Running code style linting: `yarn lint`\n\nBefore raising a pull request, make sure there are no lint problems, by running `yarn lint`. Otherwise, your pull request will be colored red.\n\n### Notes\n\n\\* AppVeyor is currently broken and ignored. PR welcome from those with Windows boxes.\n\n### Debugging\n\nTo debug tests, you'll need a recent version of chrome installed. You'll also need to add the\n`debugger` keyword where you want to pause.\n\n#### Add the word `debugger` to the code you are investigating\n\nSay you want to debug this test:\n\n```javascript\n  it('should handle overlapping server and client', () =\u003e {\n    recorder.record(newRecord(rootId, new Annotation.ServiceName('frontend')));\n```\n\nLiterally insert the word debugger\n```javascript\n  it('should handle overlapping server and client', () =\u003e {\n  debugger\n    recorder.record(newRecord(rootId, new Annotation.ServiceName('frontend')));\n```\n\n#### Run `lerna-test-debug`\n\nNow, run `lerna-test-debug`, optionally scoping to the module and test you are working on.\n\nEx.\n```bash\nnpm run lerna-test-debug -- --scope zipkin -- test/batch-recorder.integrationTest.js\n```\n\n#### Start Chrome DevTools for Node\n\nIn Chrome, open the url chrome://inspect/#devices and click \"Open dedicated DevTools for Node\"\n\n#### Skip the first breakpoint\n\nThe first breakpoint is just mocha (the test runner), skip it by clicking the play button:\n\n\u003cimg width=\"664\" alt=\"debugging\" src=\"https://user-images.githubusercontent.com/64215/60378460-693cca00-9a55-11e9-9a6b-584907048ecc.png\"\u003e\n\n#### Inspect your state!\n\nNow, you should be at a breakpoint. You can inspect the state of fields by looking at the first\nClosure scope like so:\n\n\u003cimg width=\"664\" alt=\"debugging\" src=\"https://user-images.githubusercontent.com/64215/60378478-9e491c80-9a55-11e9-9356-71e68ad21c51.png\"\u003e\n\n## Publishing\n\nIf you are a user waiting for a merged feature to get released, nag us on the related pull request or [gitter](https://gitter.im/openzipkin/zipkin).\n\nThe actual publish process is easy: Log in to npm with the `openzipkin` user. Then, run `npm run lerna-publish`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenzipkin%2Fzipkin-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenzipkin%2Fzipkin-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenzipkin%2Fzipkin-js/lists"}