Node.js

Canonical URL: https://posthog.com/docs/distributed-tracing/installation/nodejs (opens in a new tab)

Cloud region: This page uses US Cloud hosts. For an EU Cloud project, use https://eu.i.posthog.com instead of https://us.i.posthog.com (ingestion host), and use https://eu.posthog.com instead of https://app.posthog.com (app host for links).

On this page

• With posthog-node
• With OpenTelemetry
• Test your setup
• Next steps

There are two ways to send spans from Node.js.

Pick OpenTelemetry if you already run it, or if you want spans from your HTTP server and database driver without writing them yourself. Pick posthog-node if PostHog is your only tracing backend and you’d rather instrument a handful of operations by hand than add an exporter pipeline.

Both routes send OTLP spans to the same endpoint, so you can start with one and switch later without losing your traces.

With posthog-node

Minimum version: posthog-node@5.52.0 or later.

1. 1

   Install posthog-node

   Required

   npm

   bashCopy

   npm install posthog-node --save

   Yarn

   bashCopy

   yarn add posthog-node

   pnpm

   bashCopy

   pnpm add posthog-node

   Bun

   bashCopy

   bun add posthog-node

2. 2

   Enable tracing

   Required

   Tracing is off until you set the traces option. There’s no OpenTelemetry dependency to add.

   javascriptCopy

   import { PostHog } from 'posthog-node'
   
   export const posthog = new PostHog('<ph_project_token>', {
     host: 'https://us.i.posthog.com',
     traces: {
       serviceName: 'checkout-api'
   
   
   

3. 3

   Create spans

   Required

   withSpan runs a callback with a span active for its duration and ends the span for you. Spans created inside the callback nest underneath it automatically.

   javascriptCopy

   await posthog.withSpan('POST /checkout', { kind: 'server' }, async (span) => {
     span.setAttribute('plan', user.plan)
   
   
   
   
   
   

4. 4

   Link spans to people and sessions

   Recommended

   Spans created inside a PostHog request context carry posthogDistinctId and sessionId attributes, which is what makes a trace reachable from a person or a Session Replay recording.

   javascriptCopy

   posthog.withContext({ distinctId: user.id, sessionId }, async () => {
     await posthog.withSpan('POST /checkout', () => processOrder())
   })

   If you use Express, the PostHog middleware sets this up for every request, and reads the and headers that sends from the browser.

5. 5

   Flush before the process exits

   Recommended

   Queued spans are exported on an interval, so a short-lived process can exit before they’re sent. Both flush() and shutdown() export spans that have already ended.

   javascriptCopy

   export const handler = async () => {
     await posthog.withSpan('handler', () => doWork())
     await posthog.flush()
   

With OpenTelemetry

1. 1

   Install OpenTelemetry packages

   Required

   For the complete SDK reference, see the OpenTelemetry JavaScript docs (opens in a new tab).

   bashCopy

   npm install @opentelemetry/api @opentelemetry/sdk-trace-node @opentelemetry/sdk-trace-base @opentelemetry/resources @opentelemetry/semantic-conventions @opentelemetry/exporter-trace-otlp-proto

   @opentelemetry/exporter-trace-otlp-proto is the OTLP HTTP/protobuf trace exporter. The similarly named -otlp-http package sends HTTP/JSON and -otlp-grpc sends gRPC, so pick -proto to match this guide.

2. 2

   Get your project token

   Required

   You’ll need your PostHog project token to authenticate trace requests. This is the same token you use for capturing events with the PostHog SDK.

   Important: Use your project token which starts with phc_. Do not use a personal API key (which starts with phx_).

   You can find your project token in Project settings (opens in a new tab).

3. 3

   Configure the SDK

   Required

   Set up the OpenTelemetry SDK to export spans to PostHog over OTLP HTTP.

   javascriptCopy

   import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node'
   import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base'
   import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto'
   import
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   

4. 4

   Create spans

   Required

   Wrap the operations you want to measure in spans, and attach attributes for context.

   javascriptCopy

   import { trace, SpanStatusCode } from '@opentelemetry/api'
   
   const tracer = trace.getTracer('my-service')
   
   function chargeCustomer(customerId) {
   
   
   
   
   
   
   
   
   
   
   
   
   
   

5. Test your setup

   Checkpoint

   Confirm spans are reaching PostHog

   Whichever route you took:

   1. Run your application and trigger the instrumented code
   2. Open the PostHog Tracing interface
   3. Confirm your spans and traces appear

   View your traces in PostHog (opens in a new tab)

6. Next steps

   Checkpoint

   What you can do with your traces

   Action	Description
   Why you need distributed tracing (opens in a new tab)	What a trace shows you that nothing else does
   Explore traces	Read a trace as a waterfall to see where time goes
   Filter spans	Narrow down by service, status, duration, and attributes
   Propagate context	Pass trace context across services so spans join the same trace

   View your traces in PostHog (opens in a new tab)

Use your project token (the same one you use for capturing events), not a personal API key (opens in a new tab).

See the Node.js SDK docs (opens in a new tab) for batching, queue, and span-limit options, and beforeSpanSend (opens in a new tab) for scrubbing attributes or dropping spans before they’re exported.

If the callback throws or rejects, the span records the exception, its status is set to error, and your original error propagates unchanged.

Span names should be low-cardinality operation names – GET /users/:id, not GET /users/123. Variable values belong in attributes.

For work that can’t wrap a callback, startSpan returns a span you end yourself. See the Node.js SDK docs (opens in a new tab) for the full span API and for continuing a trace across services with W3C traceparent headers.

In a serverless handler, call flush() rather than shutdown(): the container is reused across invocations, so shutdown() would throw away the connection pool and the flag cache. Call shutdown() when the process is genuinely exiting.

Alternatively, configure the exporter with environment variables:

Note: Pass the full /i/v1/traces path to the traces endpoint. Don’t use the base OTEL_EXPORTER_OTLP_ENDPOINT variable, which appends its own /v1/traces.

To link spans to people and sessions, add the optional PostHog context processor to your existing provider. Use your existing PostHog client as posthog:

Use this configuration in place of the provider configuration above. Keep your existing exporter and sampler. Register the processor before requests start.

For Express, put setupExpressRequestContext (opens in a new tab) before your routes. It reads the browser tracing headers and adds missing posthogDistinctId and sessionId attributes to the active request span. The processor adds the same attributes to child spans when they start. Configure tracing_headers (opens in a new tab) for your backend hostname in the browser SDK.

For a custom integration, call enrichCurrentSpan(posthog) from posthog-node/otel after you set the IDs inside posthog.withContext(). The helper is also exported from the main posthog-node entry without loading OpenTelemetry. It requires the registered processor. It does not manage another framework’s request lifetime.

At explicit request entry, the processor also fills missing IDs on the nearest recording server ancestor through parent span objects it has observed. This covers HTTP spans that start before framework middleware. If a sampler drops an intermediate span, that parent chain cannot be verified, so the earlier server span stays unchanged. New recording spans inside the request still receive context.

Existing sessionId and posthogDistinctId span attributes take precedence. Set authenticated application identity with posthogDistinctId. Missing IDs stay absent. Express context stays active for work that the handler starts, including promises and timers that run after the response ends. A background job that needs its own IDs should start a fresh context with fresh: true. To end a context at a fixed point, pass ContextOptions.signal and abort it. The processor does not create a session, recording, trace provider, or exporter.