Google ADK observability installation

Let AI instrument your LLM calls for you

Skip the manual setup — run this in your project and the wizard installs the SDK and wires up AI Observability for you.

Learn more
PostHog Wizard hedgehog

Contents

  1. Install dependencies

    Required
    Full working example

    See the complete Node.js example on GitHub.

    Install the PostHog SDK alongside the Google Agent Development Kit for TypeScript (@google/adk). For the Python and Go ADKs, use the OpenTelemetry integration instead: they emit gen_ai.* spans that PostHog captures automatically. ADK Go sends message content as log records, so its generations arrive without prompts and responses.

    npm install @posthog/ai posthog-node @google/adk zod

  2. Add the PostHog plugin

    Required

    Create a PostHog client and register PostHogADKPlugin on your ADK Runner. The plugin hooks the run, agent, tool, and model callbacks and captures the full hierarchy: an $ai_trace per invocation, $ai_span events for agent runs and tool calls, and one $ai_generation per model call. It does not proxy your calls.

    import { FunctionTool, InMemorySessionService, LlmAgent, Runner } from '@google/adk'
    import { PostHogADKPlugin } from '@posthog/ai/adk'
    import { PostHog } from 'posthog-node'
    import { z } from 'zod'
    

    const posthog = new PostHog('<ph_project_token>', { host: 'https://us.i.posthog.com' })
    

    const getWeather = new FunctionTool({
      name: 'get_weather',
      description: 'Get the current weather for a city.',
      parameters: z.object({ city: z.string() }),
      execute: ({ city }) => `The weather in ${city} is sunny, 72F`,
    })
    

    const agent = new LlmAgent({
      name: 'assistant',
      model: 'gemini-3.6-flash',
      instruction: 'You are a helpful assistant.',
      tools: [getWeather],
    })
    

    const sessionService = new InMemorySessionService()
    const runner = new Runner({
      appName: 'my-app',
      agent,
      sessionService,
      plugins: [new PostHogADKPlugin({ client: posthog })],
    })

  3. Run your agent

    Required

    Run your agent as normal. Each invocation becomes a trace, the ADK session ID becomes $ai_session_id, and the run's userId becomes the events' distinct ID. Pass distinctId to the plugin to attribute events to a different PostHog person.

    await sessionService.createSession({
      appName: 'my-app',
      userId: 'user_123',
      sessionId: 'conversation-abc',
    })
    

    for await (const event of runner.runAsync({
      userId: 'user_123',
      sessionId: 'conversation-abc',
      newMessage: { role: 'user', parts: [{ text: "What's the weather in Paris?" }] },
    })) {
      for (const part of event.content?.parts ?? []) {
        if (part.text) {
          console.log(part.text)
        }
      }
    }

    The question above makes the agent call the tool, so this run captures:

    • a trace for the invocation
    • a span for the assistant agent run
    • a span for the get_weather tool call
    • a generation for each of the two model calls (the tool request, then the answer)

    Call await posthog.shutdown() before your process exits so batched events are flushed.

    You can expect captured $ai_generation events to have the following properties:

    PropertyDescription
    $ai_modelThe specific model, like gpt-5-mini or claude-4-sonnet
    $ai_latencyThe latency of the LLM call in seconds
    $ai_time_to_first_tokenTime to first token in seconds (streaming only)
    $ai_toolsTools and functions available to the LLM
    $ai_inputList of messages sent to the LLM
    $ai_input_tokensThe number of tokens in the input (often found in response.usage)
    $ai_output_choicesList of response choices from the LLM
    $ai_output_tokensThe number of tokens in the output (often found in response.usage)
    $ai_total_cost_usdThe total cost in USD (input + output)
    [...]See full list of properties

  4. Plugin options

    Optional

    PostHogADKPlugin accepts these options besides client:

    • distinctId: a string, or a resolver (context) => string called per model call. Defaults to the ADK userId.
    • provider: the $ai_provider label. Defaults to gemini. Set it when routing ADK to another provider so costs are derived from the right model catalog.
    • privacyMode: redacts captured input and output content.
    • groups: group analytics attached to every event.
    • properties: extra properties merged into every event.
    • captureImmediate: awaits delivery per event instead of batching. Useful in serverless environments.
    • onError: called when capturing an event fails. Capture errors never throw into the model flow.

  5. Verify traces and generations

    Recommended
    Confirm LLM events are being sent to PostHog

    Let's make sure LLM events are being captured and sent to PostHog. Under AI Observability, you should see rows of data appear in the Traces and Generations tabs.


    LLM generations in PostHog
    Check for LLM events in PostHog

  6. Next steps

    Recommended

    Now that you're capturing AI conversations, continue with the resources below to learn what else AI Observability enables within the PostHog platform.

    ResourceDescription
    BasicsLearn the basics of how LLM calls become events in PostHog.
    GenerationsRead about the $ai_generation event and its properties.
    TracesExplore the trace hierarchy and how to use it to debug LLM calls.
    SpansReview spans and their role in representing individual operations.
    Anaylze LLM performanceLearn how to create dashboards to analyze LLM performance.

Still have questions?

Was this page useful?