tracing

Integrates OpenTelemetry distributed tracing into the ergo pipeline. Extracts W3C trace context from incoming request headers, starts a root ergo.pipeline span, and returns span metadata on the domain accumulator (acc) for downstream correlation (e.g., log enrichment via logger).

When no OTEL SDK is registered, all operations are no-ops — zero overhead for the default case.

Pipeline stage: Cross-cutting (before logger)

Import

import {tracing} from '@centralping/ergo';

Options

Option	Type	Default	Description
`serviceName`	`string`	`'@centralping/ergo'`	OTEL instrumentation scope name
`version`	`string`	—	Instrumentation scope version
`tracer`	`Tracer`	—	Pre-configured tracer instance (overrides `serviceName`/`version`)
`attributes`	`object`	—	Static span attributes added to every pipeline span
`perStage`	`boolean`	`false`	Enable per-stage child spans. When true, `domainAcc.trace.tracer` is populated so `compose` creates child spans per middleware step.

Return Value

Returns span metadata stored at the accumulator path (e.g., acc.trace):

{
  span,           // Active root span (ended by handler/auto-wrap after send)
  tracer,         // Resolved tracer (only when perStage: true)
  activeContext,  // Context with span set (only when perStage: true)
  parentContext,  // Extracted parent context from request headers
  traceId: 'abc123...',
  spanId: 'def456...',
}

The span is NOT ended by this middleware — it is ended by handler or ergo-router’s auto-wrap after send() completes, capturing the full request lifecycle.

Error Responses

None. Tracing is observability-only.

import http from 'node:http';
import {
  handler, compose, tracing, logger,
} from '@centralping/ergo';

const pipeline = compose(
  tracing(),
  logger(),
  // ... remaining middleware
);

const server = http.createServer(handler(pipeline));
server.listen(3000);

import createRouter, {graceful} from '@centralping/ergo-router';

const router = createRouter({
  defaults: {
    tracing: {perStage: true},
  },
});

router.get('/health', {
  execute: () => ({response: {body: {ok: true}}}),
});

await graceful(router.handle(), {port: 3000});

RFC References

API Reference

See the auto-generated tracing API docs.