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 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(
  {fn: tracing(), setPath: "trace"},
  {fn: logger(), setPath: "log"},
  // ... 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.