Instrument Tracing

PostHogOfficialCreated by PostHog

Skill
Tool integration
Data and AI
MIT
Low risk

From the author

Add PostHog distributed tracing to see how requests flow through services and where time goes. Use after implementing features or reviewing PRs to ensure request entry points, outbound calls, and background jobs produce spans, or when asked to add tracing or spans. Also handles pointing existing OpenTelemetry tracing at PostHog and initial OTLP exporter setup.

— the description by PostHog

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a structured approach to implementing distributed tracing with PostHog. By leveraging the OpenTelemetry standard, it enables developers to track requests across services, databases, and background jobs. The process covers detection of the existing stack, configuration of OTLP exporters, and strategic placement of spans to identify performance bottlenecks and cross-service failures without requiring a proprietary PostHog SDK.

What it does

Analyzes existing codebase to detect language, framework, and current tracing setup.
Configures OpenTelemetry SDKs and OTLP HTTP exporters to send trace data to PostHog.
Implements auto-instrumentation for common frameworks and libraries.
Guides the manual addition of spans for background jobs and complex internal logic.
Links trace spans to specific users and sessions for enhanced observability.
Ensures proper flushing of trace data in serverless and short-lived environments.

When to use it

After implementing new features or reviewing pull requests to ensure proper observability.
When you need to diagnose latency issues or request flow problems across distributed services.
When tasked with adding tracing or spans to an existing application.
When migrating or pointing existing OpenTelemetry tracing configurations to PostHog.

Advantages

Uses industry-standard OpenTelemetry, avoiding vendor lock-in.
Provides deep visibility into request latency and service-to-service communication.
Supports a wide range of languages including Node.js, Python, Go, Java, .NET, PHP, and Ruby.
Enables correlation between backend traces and frontend user sessions.
Minimal impact on existing architecture through non-intrusive instrumentation.

Usage examples

“Add PostHog distributed tracing to my Python FastAPI application.”: The agent will analyze your project, install the necessary OpenTelemetry distro, configure the OTLP exporter to point to PostHog, and provide instructions for starting the app with the instrumentation wrapper.
“My Next.js app is slow. How can I see where the time is going?”: The agent will guide you through setting up OpenTelemetry in your Next.js project, specifically using the instrumentation.ts file to capture request entry points and outbound calls.

Install

Download the skill as a ZIP:
https://mp-staging.autogineer.com/agent-skills/posthog/instrument-tracing/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip instrument-tracing.zip -d .agents/skills

Documentation by PostHog

Add PostHog distributed tracing

Use this skill to add PostHog distributed tracing for new or changed code. Use it after implementing features or reviewing PRs to ensure request entry points, outbound calls, and background jobs produce spans, when the user asks to add tracing or spans, or to point existing OpenTelemetry tracing at PostHog. Supports any platform or language.

Supported platforms: Node.js, Next.js, Python (including Django, FastAPI, and Flask), Go, Java, .NET, PHP, Ruby, and any language via OpenTelemetry (OTLP).

PostHog tracing uses the standard OpenTelemetry SDK and an OTLP HTTP trace exporter. It does not need a PostHog SDK.

Instructions

Follow these steps IN ORDER:

STEP 1: Analyze the codebase and detect the platform.

Detect the language, framework, and existing tracing setup.
Look for dependency files and project files (package.json, requirements.txt, pyproject.toml, go.mod, pom.xml, build.gradle, *.csproj, Gemfile, composer.json, etc.).
Look for lockfiles (pnpm-lock.yaml, package-lock.json, yarn.lock, bun.lockb, poetry.lock, uv.lock, go.sum, Gemfile.lock, composer.lock, etc.) to determine the package manager.
Look for existing tracing: an OpenTelemetry tracer provider, an instrumentation.ts file, an opentelemetry-instrument launch command, an OpenTelemetry Collector config, a Java agent flag, or another vendor's tracing agent.
Check whether a PostHog SDK (posthog-js, posthog-node, posthog-python) is already installed. You need this only for STEP 6.

STEP 2: Choose the capture path.

If the codebase already exports OpenTelemetry traces, point the existing OTLP trace exporter (or Collector) at PostHog. Reuse the existing tracer provider. If it exports to another tracing backend, ask the user before you add PostHog as a second destination.
Otherwise, add the OpenTelemetry SDK with an OTLP HTTP trace exporter and auto-instrumentation. Auto-instrumentation creates spans for HTTP servers, frameworks, and database drivers without code changes.
Read the platform reference that matches the detected stack now. Use its "With OpenTelemetry" section. If no reference matches, use the general installation reference.

STEP 3: Install dependencies. (Skip if the codebase already exports OpenTelemetry traces.)

Install the OpenTelemetry SDK, the OTLP HTTP/protobuf trace exporter, and the auto-instrumentation for the detected stack:
- Node.js and Next.js: the packages from the platform reference, plus @opentelemetry/auto-instrumentations-node.
- Python: opentelemetry-distro and opentelemetry-exporter-otlp-proto-http, then run opentelemetry-bootstrap -a install. It installs the instrumentation packages for the libraries the app already uses. Do not install opentelemetry-instrumentation-all.
- Go: the packages from the platform reference, plus the contrib instrumentation for each library, such as go.opentelemetry.io/contrib/instrumentation/net/http/otelhttp.
- Java: the zero-code opentelemetry-javaagent.jar. It needs no dependency changes.
- .NET: OpenTelemetry, OpenTelemetry.Exporter.OpenTelemetryProtocol, and OpenTelemetry.Extensions.Hosting, plus OpenTelemetry.Instrumentation.AspNetCore and OpenTelemetry.Instrumentation.Http.
- PHP: the packages from the platform reference. For auto-instrumentation, the opentelemetry PHP extension (from PECL) and the open-telemetry/opentelemetry-auto-* package for the framework, such as open-telemetry/opentelemetry-auto-slim.
- Ruby: opentelemetry-sdk, opentelemetry-exporter-otlp, and opentelemetry-instrumentation-all, enabled with c.use_all.
Do not manually edit dependency files — use the package manager's install command.

STEP 4: Configure the OTLP trace exporter.

Send spans over OTLP HTTP/protobuf to /i/v1/traces on the PostHog host, with the project token in an Authorization: Bearer header. Do not use /i/v0/ai/otel. That endpoint accepts only LLM spans.
With environment variables, set the full path in OTEL_EXPORTER_OTLP_TRACES_ENDPOINT and the header in OTEL_EXPORTER_OTLP_TRACES_HEADERS (Authorization=Bearer <token>). Do not set the base OTEL_EXPORTER_OTLP_ENDPOINT for PostHog. It appends its own /v1/traces path.
Set OTEL_EXPORTER_OTLP_TRACES_PROTOCOL=http/protobuf where the SDK or agent defaults to gRPC. This applies to the Java agent, .NET, and Python with opentelemetry-distro.
Python with opentelemetry-distro: start the app with opentelemetry-instrument (for example, opentelemetry-instrument python app.py). It builds the tracer provider from the environment variables, so do not also build a provider in code. The distro also turns on OTLP metric and log export. Set OTEL_METRICS_EXPORTER=none and OTEL_LOGS_EXPORTER=none unless the app already sends those signals somewhere.
Set a service name (service.name, or OTEL_SERVICE_NAME) so spans are easy to find in the Tracing UI.
Start the provider before the application loads its frameworks, so auto-instrumentation can patch them. In Next.js, register the provider in instrumentation.ts behind the NEXT_RUNTIME === 'nodejs' check.
Follow the platform-specific reference for the exact configuration.
You must read a file immediately before attempting to write it.

STEP 5: Add spans where they belong.

Auto-instrumentation covers request entry points and most outbound calls. Add manual spans with the OpenTelemetry tracer API only where it has no coverage: background job handlers, queue consumers, and slow internal steps the user cares about.
Use low-cardinality span names like GET /users/:id, not GET /users/123. Put variable values in attributes.
Pass the W3C traceparent header on calls between services, so spans from each service join one trace.
Do not alter the fundamental architecture of existing files. Make additions minimal and targeted.

STEP 6: Link spans to people and sessions. (Optional.)

A span joins a person and a Session Replay recording through the posthogDistinctId and sessionId span attributes.
If the app uses posthog-js, enable tracing_headers for your API hosts. The browser then sends X-POSTHOG-DISTINCT-ID and X-POSTHOG-SESSION-ID headers on each request.
With OpenTelemetry only, copy these values onto spans yourself. In the request handler or a middleware, read the two headers and set them as the posthogDistinctId and sessionId attributes on the active request span. Skip a header that is missing or empty.
If the app already uses the PostHog SDK, it can add these attributes for you. Do not install the PostHog SDK only for this step.
- Python: add PostHogContextSpanProcessor from posthog.integrations.otel to the tracer provider. It copies the distinct ID and session ID from the active PostHog context onto each new span. Django's contexts middleware reads the headers and sets that context.
- Node.js and Python: spans created with the PostHog SDK span API (posthog.withSpan, posthog.start_span) inside a PostHog request context get these attributes automatically. This needs posthog-node 5.52.0 or later, or posthog 7.58.0 or later, with the traces option set. These spans go through the PostHog SDK, not the OpenTelemetry provider. Use this only for apps that do not run OpenTelemetry.

STEP 7: Set up environment variables.

Check if the project already has PostHog environment variables configured (e.g. in .env, .env.local, or framework-specific env files). If valid values already exist, skip this step.
If the PostHog project token is missing, use the PostHog MCP server's projects-get tool to retrieve the project's api_token. If multiple projects are returned, ask the user which project to use. If the MCP server is not connected or not authenticated, ask the user for their PostHog project token instead.
Use the project token (it starts with phc_). Do not use a personal API key (it starts with phx_).
For the PostHog host URL: check the projects-get MCP response for a region field — US maps to https://us.i.posthog.com, EU maps to https://eu.i.posthog.com. If the region is not available from the MCP response or from existing project configuration, ask the user: "Are you on PostHog US Cloud or EU Cloud?" Do not assume US Cloud.
For the OTLP traces endpoint, use https://us.i.posthog.com/i/v1/traces (US) or https://eu.i.posthog.com/i/v1/traces (EU), matching the region determined above, with the project token as an Authorization: Bearer header.
Write these values to the appropriate env file using the framework's naming convention.
Reference these environment variables in code instead of hardcoding them.

STEP 8: Flush spans in short-lived processes.

The batch processor exports spans on an interval. A script, cron job, or serverless function can stop before the batch is sent.
On Vercel and other serverless platforms, call the provider's forceFlush() before the function returns. In Next.js 15.1 and later, call it inside after() from next/server.
On AWS Lambda, call forceFlush() at the end of each invocation. Do not call shutdown() there, because the runtime reuses the container. Call shutdown() only when the process exits.

STEP 9: Verify spans arrive.

Run the application and trigger the instrumented code.
Open Tracing in the PostHog sidebar and filter by the service name. Spans should appear within a minute of sending.
If no spans appear, check the endpoint path, the Bearer token, the exporter protocol, and the flush step.

Reference files

references/nodejs.md - Node.js tracing installation
references/nextjs.md - Next.js tracing installation
references/python.md - Python tracing installation
references/go.md - Go tracing installation
references/java.md - Java tracing installation
references/dotnet.md - .net tracing installation
references/php.md - Php tracing installation
references/ruby.md - Ruby tracing installation
references/installation.md - Install tracing
references/start-here.md - Getting started with distributed tracing
references/basics.md - Why you need distributed tracing
references/COMMANDMENTS.md - Framework-specific rules the integration must follow

Each platform reference contains specific OpenTelemetry setup, OTLP configuration, and integration patterns. Find the one matching the user's stack.

Key principles

OpenTelemetry first: PostHog traces use the OpenTelemetry protocol. Use the OpenTelemetry SDK with auto-instrumentation, and reuse an existing tracer provider when there is one. The PostHog SDK is optional.
Environment variables: Always use environment variables for PostHog keys and OpenTelemetry endpoints. Never hardcode them.
Minimal changes: Add PostHog trace export alongside existing code. Don't replace or restructure existing tracing.
Boundaries, not every function: A few spans at request entry, outbound calls, and background jobs are better than a span around every function.
No secrets in attributes: Never put tokens, passwords, or other secrets in span names or attributes.

Files

ATTRIBUTION.mdAdded by AutoGineer940 B
LICENSELicence file added by AutoGineer1.0 KiB
SKILL.md11.4 KiB
references/COMMANDMENTS.md1.5 KiB
references/basics.md6.8 KiB
references/dotnet.md6.1 KiB
references/go.md6.9 KiB
references/installation.md2.5 KiB
references/java.md5.5 KiB
references/nextjs.md7.8 KiB
references/nodejs.md12.1 KiB
references/php.md6.7 KiB
references/python.md11.3 KiB
references/ruby.md3.9 KiB
references/start-here.md3.9 KiB

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.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).

	`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	Optional PostHog context processor

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.

Install posthog-node

Required

npm

npm install posthog-node --save

Yarn

yarn add posthog-node

pnpm

pnpm add posthog-node

Bun

bun add posthog-node

Enable tracing

Required

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',
  },
})

Option	Description
`serviceName`	Identifies the service in the Tracing UI. Maps to `service.name`
`serviceVersion`	Release version. Maps to `service.version`
`environment`	Deployment environment, e.g. `production`. Maps to `deployment.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 beforeSpanSend for scrubbing attributes or dropping spans before they're exported.

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.
```
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.
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.
```
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.
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.
```
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.

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-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
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.

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/traces path to the traces endpoint. Don't use the base OTEL_EXPORTER_OTLP_ENDPOINT variable, 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 link spans to people and sessions, add the optional PostHog context processor to your existing provider. Use your existing PostHog client as posthog:
```
import { PostHogContextSpanProcessor } from 'posthog-node/otel'

const provider = new NodeTracerProvider({
  resource: resourceFromAttributes({ [ATTR_SERVICE_NAME]: 'my-service' }),
  spanProcessors: [
    new PostHogContextSpanProcessor(posthog),
    new BatchSpanProcessor(exporter),
  ],
})
```
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 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 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.
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

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

View your traces in PostHog

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs an MCP server, Needs an API key, Needs Python, Needs Node.js

Security

What our scanner noticed· Low risk

Instructions that use the network

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by

PostHog

Publisher

PostHog (Official)

Source

PostHog/skills · skills/omnibus/instrument-tracing · commit a5d30e7

Licence

MIT License (redistribution allowed)

LICENSE (added by AutoGineer from LICENSE)
ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-08

AutoGineer is not affiliated with or endorsed by PostHog.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download instrument-tracing.zip

From the author

AutoGineer summary

What it does

When to use it

Advantages

Usage examples

Install

Documentation by PostHog

Add PostHog distributed tracing

Instructions

Reference files

Key principles

Files

references/nodejs.md

Node.js tracing installation

On this page

With posthog-node

Install posthog-node

npm

Yarn

pnpm

Bun

Enable tracing

Create spans

Link spans to people and sessions

Flush before the process exits

With OpenTelemetry

Install OpenTelemetry packages

Get your project token

Configure the SDK

Create spans

Test your setup

Next steps

Requirements and compatibility

Security

Attribution and licence

Related skills

Claude API

Transformers

Open Notebook

Vision Sft

LLM Evaluation

Lora Qlora Recipes

Download ZIP

With `posthog-node`