Jaeger Client Utility

1.0.1 verified Fri May 01 auth: no javascript maintenance

A lightweight wrapper around the Jaeger client (opentracing) that simplifies tracing setup and span management for Node.js services. Current stable version is 1.0.1 (last updated 2020). It provides a simple API to initialize the tracer, start spans, and inject/extract context for distributed tracing. This package is a thin layer over the official jaeger-client library, intended for quick integration but may lack flexibility for advanced use cases. No breaking changes documented; the package relies on opentracing as a peer dependency. Compared to the official jaeger-client, it reduces boilerplate but hides configuration options like sampling and reporter settings.

Common errors

error TypeError: jaegerClient.init is not a function ↓

cause In CJS, require returns the module object; the default export is not automatically assigned.

fix

Use ES import or const jaegerClient = require('jaeger-client-utility').default;

error Error: No serviceName provided. Must pass serviceName to init. ↓

cause Called init() without arguments or with a string instead of an object.

fix

Call jaegerClient.init({ serviceName: 'your-service' })

error ReferenceError: FORMAT_HTTP_HEADERS is not defined ↓

cause Missing import from opentracing package.

fix

Add import { FORMAT_HTTP_HEADERS } from 'opentracing';

Warnings

gotcha Package does not expose configuration for Jaeger agent host/port or sampler; defaults to localhost:6831 and const sampler. ↓

fix Use the official jaeger-client directly if you need custom sampler or agent location.

deprecated The opentracing API is deprecated in favor of OpenTelemetry. This package still uses opentracing. ↓

fix Consider migrating to OpenTelemetry-based instrumentation.

gotcha Package has no TypeScript type definitions; users must declare module or use @types/opentracing. ↓

fix Install @types/opentracing and create a declaration file: declare module 'jaeger-client-utility';

breaking In version 1.0.0, the default export was changed from a class to an object with methods. Previous 0.x versions used `new JaegerClient()`. ↓

fix Replace `const client = new JaegerClient()` with `import jaegerClient from 'jaeger-client-utility'` and use `jaegerClient.init()`.

Install

npm install jaeger-client-utility

yarn add jaeger-client-utility

pnpm add jaeger-client-utility

Imports

default
wrong
```
const jaegerClient = require('jaeger-client-utility')
```
correct
```
import jaegerClient from 'jaeger-client-utility'
```
Package uses default export; CommonJS require works but TypeScript users prefer ESM. In CJS, use `const jaegerClient = require('jaeger-client-utility').default` or import syntax.
jaegerClient.init
wrong
```
jaegerClient.init('my-service')
```
correct
```
jaegerClient.init({ serviceName: 'my-service' })
```
init expects an object with serviceName, not a string.

jaegerClient.startSpan

wrong

jaegerClient.startSpan('op', FORMAT_HTTP_HEADERS, headers)

correct

jaegerClient.startSpan('operationName', { isChild: { format: FORMAT_HTTP_HEADERS, injectData: headers } })

Child span context is passed as an object via the second argument, not separate parameters.

Quickstart

Initializes Jaeger tracer, starts a span, and demonstrates distributed tracing with injection and extraction.

import jaegerClient from 'jaeger-client-utility';
import { FORMAT_HTTP_HEADERS } from 'opentracing';

jaegerClient.init({ serviceName: 'my-service' });

const span = jaegerClient.startSpan('my-operation');
try {
  // Simulate work
} finally {
  span.finish();
}

// For distributed tracing:
const parentSpan = jaegerClient.startSpan('parent');
const headers = {};
jaegerClient.inject(FORMAT_HTTP_HEADERS, headers);
parentSpan.finish();

// In downstream service:
const childSpan = jaegerClient.startSpan('child', {
  isChild: {
    format: FORMAT_HTTP_HEADERS,
    injectData: headers
  }
});
childSpan.finish();