Registry / observability / zipkin-transport-http

zipkin-transport-http

JSON →
library0.22.0jsnpmunverified

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.

npm install zipkin-transport-http
INSTALL
IMPORT
SIG · ZIPKIN-TRANSPORT-H
Z
zipkin-transport-http
observabilityjavascriptv0.22.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

HttpLogger
import { HttpLogger } from 'zipkin-transport-http';
const HttpLogger = require('zipkin-transport-http').HttpLogger;
While CommonJS `require` works, ESM `import` is preferred, especially when used in TypeScript projects or modern Node.js environments.
BatchRecorder
import { BatchRecorder } from 'zipkin';
import { BatchRecorder } from 'zipkin-transport-http';
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.
jsonEncoder.JSON_V2
import { jsonEncoder } from 'zipkin';
import { jsonEncoder } from 'zipkin-transport-http';
The `jsonEncoder` is typically imported from the core `zipkin` package to specify the data format for the HTTP transport, often used to configure `HttpLogger`.

Demonstrates initializing `HttpLogger` with `node-fetch`, integrating it into a `BatchRecorder`, and creating a `Tracer` to send a simple span to a Zipkin collector.

import { HttpLogger } from 'zipkin-transport-http'; import { BatchRecorder, Tracer, jsonEncoder } from 'zipkin'; import { SomeContextManager } from 'zipkin-context-cls'; // Or 'zipkin-context-koa', etc. import fetch from 'node-fetch'; // Peer dependency const ZIPKIN_COLLECTOR_URL = process.env.ZIPKIN_COLLECTOR_URL ?? 'http://localhost:9411/api/v2/spans'; const SERVICE_NAME = process.env.SERVICE_NAME ?? 'my-service'; // 1. Create an HTTP Logger const httpLogger = new HttpLogger({ endpoint: ZIPKIN_COLLECTOR_URL, fetch: fetch, jsonEncoder: jsonEncoder.JSON_V2, }); // 2. Create a BatchRecorder with the HTTP Logger const recorder = new BatchRecorder({ logger: httpLogger, }); // 3. Create a Tracer const tracer = new Tracer({ ctxImpl: new SomeContextManager(SERVICE_NAME), // Replace with your chosen context manager recorder: recorder, localServiceName: SERVICE_NAME, }); // Example: Start a new trace and record a span async function doSomeWork() { const rootSpan = tracer.startRootSpan('root-operation'); tracer.scoped(() => { // Perform some work here console.log('Doing some traced work...'); tracer.addBinaryAnnotation('http.url', '/my-endpoint'); tracer.addBinaryAnnotation('http.status_code', '200'); }); rootSpan.finish(); console.log('Trace finished and sent to Zipkin.'); } doSomeWork(); // In a real application, you'd likely want to ensure all spans are flushed on exit. // recorder.flush() can be called manually if needed (e.g., in serverless environments).
Debug
Known issues
breakingSupport 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.
fix
Upgrade your Node.js runtime to version 10 or higher. For LTS recommendations, refer to Node.js official release schedule.
affects: >=0.21.0
breakingSupport 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.
fix
Upgrade your Node.js runtime to version 8 or higher (preferably 10+ due to the subsequent drop of Node.js 8 support).
affects: >=0.17.1
gotchaThe `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.
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`.
affects: >=0.16.2
gotchaOlder versions of this package (prior to `0.18.6`) could throw `Error: Must be valid TraceId instance` due to transpilation issues.
fix
Upgrade `zipkin-transport-http` to version `0.18.6` or newer to resolve this specific error.
affects: <0.18.6
Errors
Common errors & fixes
TypeError: fetch is not a function
The `node-fetch` peer dependency was not installed or not correctly passed to the `HttpLogger` constructor.
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.
Error: Must be valid TraceId instance
This error often occurs in older versions (<0.18.6) due to issues with how `TraceId` instances were handled during transpilation.
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.
No spans were sent to the Zipkin collector.
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.
fix
For short-lived processes, manually call `recorder.flush()` before the process exits. For example, `await new Promise(resolve => recorder.flush(() => resolve()));`
Upgrade
Version history
0.22.0latest on npm
Audit
Dependencies
node-fetchrequiredRequired for making HTTP requests to the Zipkin collector. It's a peer dependency, so you must install it separately.
Agent activity
46 hits · last 30 days
node
36
OpenAI (training)
1
Resources
zipkin-transport-http — npm install zipkin-transport-http · libregistry