Zipkin HTTP Transport

Common errors

• TypeError: fetch is not a function

  cause 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

  cause 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.

  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.
  fix For short-lived processes, manually call `recorder.flush()` before the process exits. For example, `await new Promise(resolve => recorder.flush(() => resolve()));`

Warnings

• breaking 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.
  Fix: Upgrade your Node.js runtime to version 10 or higher. For LTS recommendations, refer to Node.js official release schedule.
• breaking 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.
  Fix: Upgrade your Node.js runtime to version 8 or higher (preferably 10+ due to the subsequent drop of Node.js 8 support).
• gotcha 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.
  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`.
• gotcha Older 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.

Install

• npm install zipkin-transport-http npm
• yarn add zipkin-transport-http yarn
• pnpm add zipkin-transport-http pnpm

Imports

• HttpLogger
  wrong:

  const HttpLogger = require('zipkin-transport-http').HttpLogger;

  correct:

  import { HttpLogger } from 'zipkin-transport-http';

  While CommonJS `require` works, ESM `import` is preferred, especially when used in TypeScript projects or modern Node.js environments.
• BatchRecorder
  wrong:

  import { BatchRecorder } from 'zipkin-transport-http';

  correct:

  import { BatchRecorder } from 'zipkin';

  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
  wrong:

  import { jsonEncoder } from 'zipkin-transport-http';

  correct:

  import { jsonEncoder } from 'zipkin';

  The `jsonEncoder` is typically imported from the core `zipkin` package to specify the data format for the HTTP transport, often used to configure `HttpLogger`.

Quickstart

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).