@vizydrop/tracer

OpenTelemetry tracing wrapper for Vizydrop/Targetprocess Node.js services. Provides auto-instrumentation, metric collection, and correlation ID capture middleware for Express and Koa.

Installation

yarn add @vizydrop/tracer

Usage

Basic Setup

import {createTracer} from '@vizydrop/tracer';

const {trace, agent} = createTracer({
    openTelemetryOptions: {
        serviceName: 'my-service',
        serviceVersion: '1.0.0',
        clusterName: 'production',
        environment: 'prod',
    },
});

// Use trace API for manual spans
const tracer = trace.getTracer('my-module');

// Graceful shutdown
process.on('SIGTERM', () => agent.shutdown());

Express Middleware

Captures correlation ID from the request and attaches it to the active OpenTelemetry span.

import {express} from '@vizydrop/tracer';

app.use(express.captureCorrelationIdMiddleware((req) => req.headers['x-correlation-id']));

Koa Middleware

import {koa} from '@vizydrop/tracer';

app.use(koa.captureCorrelationIdMiddleware((request) => request.headers['x-correlation-id']));

Configuration

| Option | Type | Default | Description | |--------|------|---------|-------------| | enabled | boolean | true | Enable/disable tracing instrumentation | | serviceName | string | — | Service name reported to the collector | | serviceVersion | string | — | Service version reported to the collector | | clusterName | string | — | Cluster name (custom tp_cluster attribute) | | environment | string | — | Deployment environment | | metricsIntervalMillis | number | 1000 | Metric export interval in milliseconds | | ignoreUrls | (string \| RegExp)[] | See below | URLs to exclude from tracing | | flushToConsole | boolean | false | Output traces/metrics to console instead of OTLP | | traceExporterOptions | object | — | Options passed to OTLPTraceExporter | | metricExporterOptions | object | — | Options passed to OTLPMetricExporter | | getSpanAttributes | () => Record<string, string \| undefined> | — | Function that returns custom attributes to attach to every span on start. Useful for injecting context like correlation IDs or user metadata from CLS/async storage into all outgoing spans. |

Default Ignored URLs

• /metrics, /_prometheus/metrics
• /assets/*
• /favicon*
• /api/v1/status
• /status

Features

• Automatic HTTP instrumentation via @opentelemetry/auto-instrumentations-node
• Sensitive data stripping from span names (tokens, session IDs, secrets)
• OTLP/gRPC export for traces and metrics
• Console export mode for local development
• Correlation ID capture middleware for Express and Koa
• Custom span attributes via getSpanAttributes (e.g., inject correlation IDs from async context)

Custom Span Attributes

Use getSpanAttributes to inject dynamic attributes (e.g., correlation ID from CLS) into every span:

import {createTracer} from '@vizydrop/tracer';
import {correlationId} from '@vizydrop/correlation-id';

const {trace, agent} = createTracer({
    openTelemetryOptions: {
        serviceName: 'my-service',
        getSpanAttributes: () => ({
            'correlation.id': correlationId.getId(),
            'user.email': correlationId.getMetadata()?.email,
        }),
    },
});

Development

yarn install
yarn build       # Compile TypeScript
yarn test        # Run tests
yarn lint        # Run ESLint