references/nodejs.md
AI agents: this is one page from PostHog's docs. Full index of Markdown docs for LLMs: https://posthog.com/llms.txt
Node.js tracing installation
Canonical URL: https://posthog.com/docs/distributed-tracing/installation/nodejs
Cloud region: This page uses US Cloud hosts. For an EU Cloud project, use
https://eu.i.posthog.cominstead ofhttps://us.i.posthog.com(ingestion host), and usehttps://eu.posthog.cominstead ofhttps://app.posthog.com(app host for links).
On this page
There are two ways to send spans from Node.js.
| | posthog-node | OpenTelemetry |
| --- | --- | --- |
| Packages | The SDK you already use for analytics | Six @opentelemetry/* packages |
| Instrumentation | Manual – you wrap the operations you care about | Manual, plus auto-instrumentation for HTTP, Express, databases, and more |
| Person and session join | Automatic inside a PostHog request context | Set the attributes yourself |
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:
[email protected]or later.
-
1
Install posthog-node
Required
npm
npm install posthog-node --saveYarn
yarn add posthog-nodepnpm
pnpm add posthog-nodeBun
bun add posthog-node -
2
Enable tracing
Required
Tracing is off until you set the
tracesoption. 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', }, })| Option | Description | | --- | --- | |
serviceName| Identifies the service in the Tracing UI. Maps toservice.name| |serviceVersion| Release version. Maps toservice.version| |environment| Deployment environment, e.g.production. Maps todeployment.environment| |resourceAttributes| Additional OpenTelemetry resource attributes |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
beforeSpanSendfor scrubbing attributes or dropping spans before they're exported. -
3
Create spans
Required
withSpanruns 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, notGET /users/123. Variable values belong in attributes.For work that can't wrap a callback,
startSpanreturns a span you end yourself. See the Node.js SDK docs for the full span API and for continuing a trace across services with W3Ctraceparentheaders. -
4
Link spans to people and sessions
Recommended
Spans created inside a PostHog request context carry
posthogDistinctIdandsessionIdattributes, 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-IDandX-POSTHOG-SESSION-IDheaders thattracing_headerssends from the browser. -
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()andshutdown()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 thanshutdown(): the container is reused across invocations, soshutdown()would throw away the connection pool and the flag cache. Callshutdown()when the process is genuinely exiting.
With OpenTelemetry
-
1
Install OpenTelemetry packages
Required
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-protois the OTLP HTTP/protobuf trace exporter. The similarly named-otlp-httppackage sends HTTP/JSON and-otlp-grpcsends gRPC, so pick-prototo match this guide. -
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 withphx_).You can find your project token in Project settings.
-
3
Configure the SDK
Required
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/tracespath to the traces endpoint. Don't use the baseOTEL_EXPORTER_OTLP_ENDPOINTvariable, which appends its own/v1/traces. -
4
Create spans
Required
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
posthogDistinctIdandsessionIdattributes yourself, from theX-POSTHOG-DISTINCT-IDandX-POSTHOG-SESSION-IDheaders thattracing_headerssends from the browser. -
Test your setup
Checkpoint
Confirm spans are reaching PostHog
Whichever route you took:
- Run your application and trigger the instrumented code
- Open the PostHog Tracing interface
- Confirm your spans and traces appear
-
Next steps
Checkpoint
What you can do with your traces
| Action | Description | | --- | --- | | Why you need distributed tracing | 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 |