AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

instrument-tracing

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.

Original source
posthog
License
MIT
Pinned revision
cac7c80a9e5b73484d18eda1bffb47297c938e0c

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

Ask your assistant

Use Agentic Memory skills to read posthog--instrument-tracing at revision cac7c80a9e5b73484d18eda1bffb47297c938e0c, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 13

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

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

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

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

  3. 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/traces path to the traces endpoint. Don't use the base OTEL_EXPORTER_OTLP_ENDPOINT variable, which appends its own /v1/traces.

  4. 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 posthogDistinctId and sessionId attributes yourself, from the X-POSTHOG-DISTINCT-ID and X-POSTHOG-SESSION-ID headers that tracing_headers sends from the browser.

  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

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