tracing-node¶
@saidsef/tracing-node wraps the OpenTelemetry Node SDK. One call to setupTracing builds the tracer, meter and logger providers, registers them globally, and turns on a fixed set of instrumentations. An application gets all three signals without assembling exporters, span processors, resource detectors and instrumentation packages itself.
Initialisation is idempotent. A second call to setupTracing logs a warning and returns the tracer from the provider that already exists, which keeps a library that initialises tracing from fighting an application that does the same.
Features¶
| Feature | Description |
|---|---|
| HTTP/HTTPS instrumentation | Client and server spans, with health and metrics probes ignored |
| fetch/undici instrumentation | Outgoing globalThis.fetch calls |
| Express instrumentation | Route spans named METHOD /route, with params, query and user id |
| Connect instrumentation | Middleware spans for Connect applications |
| Elasticsearch client | Database spans, when the optional instrumentation package is installed |
| IORedis client | Cache spans named redis.COMMAND |
| AWS SDK | Cloud service spans, with SQS context propagation from the payload |
| Pino logger | Trace and span ids injected into log records |
| DNS and FS instrumentation | Off by default, enabled per option |
| Resource detection | Environment, host, OS, process and service instance id |
| Service graph attributes | peer.service set for HTTP, fetch, Redis, Elasticsearch and AWS calls |
| W3C Trace Context | Trace context and baggage propagation |
Requirements¶
| Requirement | Value |
|---|---|
| Node | >= 24.0.0 |
| Module system | ESM ("type": "module"); an ESM or CommonJS application is patched behind an --import preload |
| Collector | Any endpoint accepting OTLP over gRPC |
Quick start¶
npm install @saidsef/tracing-node --save
// instrument.mjs
import {setupTracing} from '@saidsef/tracing-node';
setupTracing({serviceName: 'my-service', url: 'http://alloy:4317'});
node --import ./instrument.mjs ./app.mjs
serviceName and url are required. Both fall back to the SERVICE_NAME and ENDPOINT environment variables. The preload matters: an instrumented package imported statically alongside the library loads too early to be patched. Configuration covers the full option set and the order in which tracing has to be initialised.
Where the traces go¶
The exporter speaks OTLP over gRPC, which any OpenTelemetry-compatible collector or backend accepts. Point url at yours.
grafana-loki-on-k8s is a companion project that deploys the LGTM+ stack - Grafana, Prometheus, Mimir, Loki, Tempo, Pyroscope, Alloy and Beyla - to Kubernetes. Deployment covers pointing a service at its Alloy receiver, with the environment variables and manifests.
Documentation¶
| Page | Contents |
|---|---|
| Architecture | The pipeline setupTracing builds, and how the service graph is fed |
| Configuration | Options, environment variables, initialisation order and shutdown |
| Instrumentation | Each instrumentation, and the attributes it emits |
| Deployment | Running instrumented services in containers and Kubernetes |
| Testing | The unit tests and the end to end harness |
| Troubleshooting | Symptoms, causes and fixes |
Repository¶
Source code and releases: github.com/saidsef/tracing-node