{"id":16283,"library":"zipkin-transport-http","title":"Zipkin HTTP Transport","description":"This package, `zipkin-transport-http`, provides the official HTTP transport mechanism for sending Zipkin trace data to a Zipkin collector server. It is a core component within the larger `zipkin-js` ecosystem, designed to integrate seamlessly with other `zipkin-js` packages like `zipkin` (for `BatchRecorder`) and various instrumentation libraries. The current stable version is `0.22.0`, released recently with improvements like a fallback for `fetch` and fixes. The project maintains a fairly active release cadence, frequently addressing bugs, adding new features such as configurable `fetch` API and SQS support in related packages, and improving TypeScript interfaces. Its primary differentiator is its deep integration and official support within the OpenZipkin JavaScript tracing suite, ensuring compatibility and alignment with Zipkin's tracing specifications.","status":"active","version":"0.22.0","language":"javascript","source_language":"en","source_url":"https://github.com/openzipkin/zipkin-js","tags":["javascript","typescript"],"install":[{"cmd":"npm install zipkin-transport-http","lang":"bash","label":"npm"},{"cmd":"yarn add zipkin-transport-http","lang":"bash","label":"yarn"},{"cmd":"pnpm add zipkin-transport-http","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required for making HTTP requests to the Zipkin collector. It's a peer dependency, so you must install it separately.","package":"node-fetch","optional":false}],"imports":[{"note":"While CommonJS `require` works, ESM `import` is preferred, especially when used in TypeScript projects or modern Node.js environments.","wrong":"const HttpLogger = require('zipkin-transport-http').HttpLogger;","symbol":"HttpLogger","correct":"import { HttpLogger } from 'zipkin-transport-http';"},{"note":"The `BatchRecorder` is part of the core `zipkin` package, not this transport package. It is essential for collecting and buffering spans before they are sent by the transport.","wrong":"import { BatchRecorder } from 'zipkin-transport-http';","symbol":"BatchRecorder","correct":"import { BatchRecorder } from 'zipkin';"},{"note":"The `jsonEncoder` is typically imported from the core `zipkin` package to specify the data format for the HTTP transport, often used to configure `HttpLogger`.","wrong":"import { jsonEncoder } from 'zipkin-transport-http';","symbol":"jsonEncoder.JSON_V2","correct":"import { jsonEncoder } from 'zipkin';"}],"quickstart":{"code":"import { HttpLogger } from 'zipkin-transport-http';\nimport { BatchRecorder, Tracer, jsonEncoder } from 'zipkin';\nimport { SomeContextManager } from 'zipkin-context-cls'; // Or 'zipkin-context-koa', etc.\nimport fetch from 'node-fetch'; // Peer dependency\n\nconst ZIPKIN_COLLECTOR_URL = process.env.ZIPKIN_COLLECTOR_URL ?? 'http://localhost:9411/api/v2/spans';\nconst SERVICE_NAME = process.env.SERVICE_NAME ?? 'my-service';\n\n// 1. Create an HTTP Logger\nconst httpLogger = new HttpLogger({\n  endpoint: ZIPKIN_COLLECTOR_URL,\n  fetch: fetch,\n  jsonEncoder: jsonEncoder.JSON_V2,\n});\n\n// 2. Create a BatchRecorder with the HTTP Logger\nconst recorder = new BatchRecorder({\n  logger: httpLogger,\n});\n\n// 3. Create a Tracer\nconst tracer = new Tracer({\n  ctxImpl: new SomeContextManager(SERVICE_NAME), // Replace with your chosen context manager\n  recorder: recorder,\n  localServiceName: SERVICE_NAME,\n});\n\n// Example: Start a new trace and record a span\nasync function doSomeWork() {\n  const rootSpan = tracer.startRootSpan('root-operation');\n  tracer.scoped(() => {\n    // Perform some work here\n    console.log('Doing some traced work...');\n    tracer.addBinaryAnnotation('http.url', '/my-endpoint');\n    tracer.addBinaryAnnotation('http.status_code', '200');\n  });\n  rootSpan.finish();\n  console.log('Trace finished and sent to Zipkin.');\n}\n\ndoSomeWork();\n\n// In a real application, you'd likely want to ensure all spans are flushed on exit.\n// recorder.flush() can be called manually if needed (e.g., in serverless environments).","lang":"typescript","description":"Demonstrates initializing `HttpLogger` with `node-fetch`, integrating it into a `BatchRecorder`, and creating a `Tracer` to send a simple span to a Zipkin collector."},"warnings":[{"fix":"Upgrade your Node.js runtime to version 10 or higher. For LTS recommendations, refer to Node.js official release schedule.","message":"Support for Node.js 8 was dropped starting with version `0.21.0`. Projects running on Node.js 8 or older will not receive updates and should upgrade their Node.js environment.","severity":"breaking","affected_versions":">=0.21.0"},{"fix":"Upgrade your Node.js runtime to version 8 or higher (preferably 10+ due to the subsequent drop of Node.js 8 support).","message":"Support for Node.js 6 was dropped starting with version `0.17.1`. Applications relying on Node.js 6 will need to upgrade to continue using newer versions of this package.","severity":"breaking","affected_versions":">=0.17.1"},{"fix":"Install `node-fetch` in your project: `npm install node-fetch@\"^2.6.7\"` (or `yarn add node-fetch@\"^2.6.7\"`). Note the peer dependency range `^1.4.0 <3.0.0` for `node-fetch`.","message":"The `node-fetch` package is a peer dependency and must be explicitly installed alongside `zipkin-transport-http`. Failure to do so will result in runtime errors when attempting to send spans.","severity":"gotcha","affected_versions":">=0.16.2"},{"fix":"Upgrade `zipkin-transport-http` to version `0.18.6` or newer to resolve this specific error.","message":"Older versions of this package (prior to `0.18.6`) could throw `Error: Must be valid TraceId instance` due to transpilation issues.","severity":"gotcha","affected_versions":"<0.18.6"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure `node-fetch` is installed (`npm install node-fetch`) and passed explicitly as the `fetch` option during `HttpLogger` instantiation: `new HttpLogger({ endpoint: '...', fetch: require('node-fetch') })` or `fetch: fetch` if using ESM.","cause":"The `node-fetch` peer dependency was not installed or not correctly passed to the `HttpLogger` constructor.","error":"TypeError: fetch is not a function"},{"fix":"Upgrade `zipkin-transport-http` to version `0.18.6` or newer. If the problem persists, ensure your Babel/TypeScript configuration is not aggressively transpiling `zipkin`'s internal classes.","cause":"This error often occurs in older versions (<0.18.6) due to issues with how `TraceId` instances were handled during transpilation.","error":"Error: Must be valid TraceId instance"},{"fix":"For short-lived processes, manually call `recorder.flush()` before the process exits. For example, `await new Promise(resolve => recorder.flush(() => resolve()));`","cause":"Spans are buffered by `BatchRecorder` and sent periodically or when the buffer is full. In short-lived processes (e.g., serverless functions, scripts), the process might exit before spans are flushed.","error":"No spans were sent to the Zipkin collector."}],"ecosystem":"npm"}