Zipkin Express Instrumentation

0.22.0 verified Sat Apr 25 auth: no javascript maintenance

Express middleware for distributed tracing with Zipkin.js. Version 0.22.0 is current stable, released as part of the openzipkin/zipkin-js monorepo with irregular release cadence. This package provides middleware that creates Zipkin spans for incoming HTTP requests to Express applications, automatically recording timing, tags, and annotations. Key differentiators: minimal configuration, tight integration with Zipkin's B3 propagation headers, support for custom sampler and tracer configurations. Suitable for Node.js Express apps requiring observability via Zipkin. Note: Not actively maintained (last release 0.22.0).

Common errors

error Error: Must be valid TraceId instance ↓

cause Incorrect or missing tracer configuration leads to invalid Zipkin trace IDs.

fix

Ensure Tracer is initialized with a valid sampler and recorder.

error TypeError: Cannot destructure property 'tracer' of 'undefined' or 'null' ↓

cause expressMiddleware() called without options object or missing tracer property.

fix

Call expressMiddleware({ tracer }) where tracer is a valid Zipkin Tracer instance.

Warnings

deprecated Require-style import of zipkin modules may break in future versions; prefer ESM imports. ↓

fix Use import instead of require() for all zipkin packages.

gotcha expressMiddleware must be added before route handlers to trace all requests. ↓

fix Ensure the middleware is applied before app.get(), app.post(), etc.

gotcha Tracer's localServiceName must be set; otherwise, spans may be missing service name. ↓

fix Provide localServiceName when creating Tracer instance.

Install

npm install zipkin-instrumentation-express

yarn add zipkin-instrumentation-express

pnpm add zipkin-instrumentation-express

Imports

expressMiddleware

wrong

const expressMiddleware = require('zipkin-instrumentation-express')

correct

import { expressMiddleware } from 'zipkin-instrumentation-express'

ESM and CommonJS both supported; TypeScript types included.

expressMiddleware (default)

wrong

import { expressMiddleware as default } from 'zipkin-instrumentation-express'

correct

import expressMiddleware from 'zipkin-instrumentation-express'

Package has a default export as well as named export; both work.

Quickstart

Sets up Zipkin tracing middleware for Express app using batch recorder and HTTP transport.

import { Tracer, BatchRecorder, jsonEncoder } from 'zipkin';
import { HttpLogger } from 'zipkin-transport-http';
import { expressMiddleware } from 'zipkin-instrumentation-express';
import express from 'express';

const tracer = new Tracer({
  recorder: new BatchRecorder({
    logger: new HttpLogger({
      endpoint: process.env.ZIPKIN_ENDPOINT || 'http://localhost:9411/api/v2/spans',
      jsonEncoder: jsonEncoder.JSON_V2
    })
  }),
  localServiceName: 'my-service'
});

const app = express();
app.use(expressMiddleware({ tracer }));

app.get('/', (req, res) => res.send('Hello tracing!'));
app.listen(3000);