OpenCode AI Observability installation

Contents

  1. Prerequisites

    Required

    OpenCode is an open-source AI coding agent that runs in your terminal. The @posthog/opencode plugin captures LLM generations, tool executions, and conversation traces as $ai_generation, $ai_span, and $ai_trace events and sends them to PostHog.

    You need:

  2. Install the plugin

    Required

    Add @posthog/opencode to the plugin array in your opencode.json file:

    {
      "$schema": "https://opencode.ai/config.json",
      "plugin": ["@posthog/opencode"]
    }

    Use opencode.json in your project root for a project-level install, or ~/.config/opencode/opencode.json for a global install. OpenCode installs the package when it starts and caches it in ~/.cache/opencode/node_modules/.

  3. Configure PostHog

    Required

    Set environment variables with your PostHog project token and host. You can find both in your PostHog project settings.

    export POSTHOG_API_KEY="<ph_project_token>"
    export POSTHOG_HOST="https://us.i.posthog.com"

    Tip: Add these variables to your shell profile, such as ~/.zshrc or ~/.bashrc, so they persist across sessions.

    If POSTHOG_API_KEY is not set, the plugin does not capture or send events.

  4. Run a session

    Required

    Start OpenCode as normal and use it for a task:

    opencode

    The plugin initializes and captures events for each LLM call, tool execution, and completed prompt.

  5. Configuration options

    Optional

    Configure the plugin with environment variables:

    VariableDefaultDescription
    POSTHOG_API_KEY(required)Your PostHog project token
    POSTHOG_HOSThttps://us.i.posthog.comPostHog ingestion host
    POSTHOG_PRIVACY_MODEfalseWhen true, the plugin does not send LLM content, prompts, or tool inputs and outputs. Token counts, costs, latency, and model metadata are still captured.
    POSTHOG_ENABLEDtrueSet to false to disable the plugin
    POSTHOG_DISTINCT_IDMachine hostnameDistinct ID included in all events
    POSTHOG_PROJECT_NAMECurrent directory nameProject name included in all events
    POSTHOG_TAGS(none)Custom tags added to all events in key1:val1,key2:val2 format
    POSTHOG_MAX_ATTRIBUTE_LENGTH12000Maximum length for serialized tool input and output attributes

    Privacy mode

    When POSTHOG_PRIVACY_MODE=true, all LLM content, user prompts, tool inputs, and tool outputs are redacted. Token counts, costs, latency, and model metadata are still captured.

    The plugin always redacts sensitive keys matching terms such as api_key, token, secret, password, authorization, credential, and private_key, regardless of privacy mode.

    What gets captured

    The plugin captures three types of events:

    • $ai_generation: Each LLM call, including model, provider, token usage, cost, stop reason, and input and output messages in OpenAI chat format.
    • $ai_span: Each tool execution, including tool name, input parameters, output result, duration, parent generation, and error details. Learn more about spans.
    • $ai_trace: Each completed prompt, including aggregated token totals, latency, input and output state, and error status. Learn more about traces.

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

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

Was this page useful?