Node.js tracing installation

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

import { PostHog } from 'posthog-node'

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

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

See the Node.js SDK docs for batching, queue and span-limit options, and beforeSpanSend for scrubbing attributes or dropping spans before they're exported.

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.

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

  const order = await posthog.withSpan('create-order', () => createOrder(cart))
  await posthog.withSpan('charge-card', () => stripe.charge(order))

  return order
})

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 for the full span API and for continuing a trace across services with W3C traceparent headers.

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.

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 X-POSTHOG-DISTINCT-ID and X-POSTHOG-SESSION-ID headers that tracing_headers sends from the browser.

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.

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

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.

For the complete SDK reference, see the OpenTelemetry JavaScript docs.

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.

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.

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

import { NodeTracerProvider } from '@opentelemetry/sdk-trace-node'
import { BatchSpanProcessor } from '@opentelemetry/sdk-trace-base'
import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-proto'
import { resourceFromAttributes } from '@opentelemetry/resources'
import { ATTR_SERVICE_NAME } from '@opentelemetry/semantic-conventions'

const exporter = new OTLPTraceExporter({
  url: 'https://us.i.posthog.com/i/v1/traces',
  headers: {
    Authorization: 'Bearer <ph_project_token>',
  },
})

const provider = new NodeTracerProvider({
  resource: resourceFromAttributes({
    [ATTR_SERVICE_NAME]: 'my-service',
  }),
  spanProcessors: [new BatchSpanProcessor(exporter)],
})

provider.register()

Alternatively, configure the exporter with environment variables:

OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://us.i.posthog.com/i/v1/traces"
OTEL_EXPORTER_OTLP_TRACES_HEADERS="Authorization=Bearer <ph_project_token>"
OTEL_EXPORTER_OTLP_TRACES_PROTOCOL="http/protobuf"
OTEL_SERVICE_NAME="my-service"

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.

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

import { trace, SpanStatusCode } from '@opentelemetry/api'

const tracer = trace.getTracer('my-service')

function chargeCustomer(customerId) {
  return tracer.startActiveSpan('charge-customer', (span) => {
    try {
      span.setAttribute('customer.id', customerId)
      // ... do work ...
      span.setStatus({ code: SpanStatusCode.OK })
    } catch (err) {
      span.recordException(err)
      span.setStatus({ code: SpanStatusCode.ERROR })
      throw err
    } finally {
      span.end()
    }
  })
}

To join these spans to a person or a Session Replay recording, set posthogDistinctId and sessionId attributes yourself, from the X-POSTHOG-DISTINCT-ID and X-POSTHOG-SESSION-ID headers that tracing_headers sends from the browser.

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