---
title: PostHog
description: Send agent traces and generations to PostHog AI Observability.
type: instrumentation
keywords:
  - otel
  - opentelemetry
  - tracing
  - observability
  - generations
  - analytics
---

# PostHog

Instrumentation integration for eve. Send agent traces and generations to PostHog AI Observability.

## Install

Add PostHog AI Observability from eve's registry:

```bash
eve add instrumentation/posthog
```

## Quick start

eve installs `agent/instrumentation.ts` with PostHog's trace exporter. It also links spans to the user who initiated the session when an authenticated principal is available:

```ts
// agent/instrumentation.ts
import { trace } from "@opentelemetry/api";
import { SimpleSpanProcessor } from "@opentelemetry/sdk-trace-base";
import { PostHogTraceExporter } from "@posthog/ai/otel";
import { registerOTel } from "@vercel/otel";
import { defineInstrumentation } from "eve/instrumentation";

export default defineInstrumentation({
  setup: ({ agentName }) =>
    registerOTel({
      serviceName: agentName,
      spanProcessors: [
        new SimpleSpanProcessor(
          new PostHogTraceExporter({
            projectToken: process.env.POSTHOG_PROJECT_TOKEN!,
            host: process.env.POSTHOG_HOST,
          }),
        ),
      ],
    }),
  events: {
    "step.started"(input) {
      const distinctId =
        input.session.auth.initiator?.principalId ??
        input.session.auth.current?.principalId;

      if (!distinctId) return undefined;

      trace.getActiveSpan()?.setAttribute("posthog.distinct_id", distinctId);
      return { runtimeContext: { posthog_distinct_id: distinctId } };
    },
  },
});
```

## Configure

Copy your project token and client API host from PostHog's project settings and expose them as `POSTHOG_PROJECT_TOKEN` and `POSTHOG_HOST`. Remove the `events` handler to capture generations anonymously. PostHog groups turns using `eve.session.id` and preserves eve's trace hierarchy. See [PostHog's eve installation guide](https://posthog.com/docs/ai-observability/installation/eve) for verification steps and the [instrumentation guide](/docs/guides/instrumentation) for input and output capture controls.

[Read the full instrumentation documentation](/docs/guides/instrumentation)

---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)