#telemetry

@tsdevstack/telemetry sets up tracing for a process: one OpenTelemetry setup that sends traces to Cloud Trace, X-Ray or Azure Monitor in the cloud and to Jaeger locally. NestJS services and workers get it through @tsdevstack/nest-common, with nothing to call. Next.js frontends call it from instrumentation.ts.

npm install @tsdevstack/telemetry

#Next.js

// instrumentation.ts
import packageJson from './package.json';

export async function register(): Promise<void> {
  if (process.env.NEXT_RUNTIME === 'nodejs') {
    const { registerTelemetry } = await import('@tsdevstack/telemetry');
    registerTelemetry({
      serviceName: packageJson.name,
      serviceVersion: packageJson.version,
      continueIncomingTraces: false,
    });
  }
}

continueIncomingTraces: false makes the frontend start a new trace for every request, so a browser can't choose the trace. The frontend's own calls still carry its trace to Kong.

Add the interceptor to the axios clients that call Kong:

import { injectTraceContext } from '@tsdevstack/telemetry';

authClient.instance.interceptors.request.use(injectTraceContext);

#API

#registerTelemetry(options?)

Registers the tracer provider, the async context and the W3C traceparent propagator globally. Call it once, before the app handles requests. It returns { forceFlush(), shutdown() }.

#injectTraceContext(config)

An axios request interceptor. It writes the current trace into the request's traceparent header, so the called service continues the trace. A call outside any trace gets no header.

#resolveTelemetryProvider(value?)

The cloud the process runs on, from the value or TELEMETRY_PROVIDER: 'gcp', 'aws', 'azure', or 'local' for anything else.

#toXrayTraceId(traceId)

A W3C trace ID in X-Ray's form (1-xxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxx), as the X-Ray console shows it.

#Where traces go

The tsdevstack deploy sets every variable above. The sample rate comes from TRACE_SAMPLE_RATE (0 to 1, default 1): a request whose parent span was kept stays in the trace, and any other request is kept at that rate. Health probes and metrics scrapes (/health, /health/..., /metrics) are never traced. OTEL_RESOURCE_ATTRIBUTES adds resource attributes.

All exports use OTLP over HTTP with protobuf. Each cloud's sign-in code loads only on that cloud.

See Traces and Dashboards for what a trace contains and where to look at it.