Trace ingestion setup

You are being asked to configure trace capture for the harness you are running in (pi agent, Claude Code, Codex, or any OTLP/HTTP JSON exporter).

1. Detect your harness. Skip this if the user already told you which one they use.
2. Follow the matching section below to install the plugin and prepare its config.
3. When a config needs the API key, ask the user to choose one of:
   • Paste the API key into the chat so you can fill in the config yourself. Warn them first that the key becomes part of the conversation and may be sent to the model provider.
   • Fill in the key themselves: print the exact config with <API_KEY> placeholders and let them replace it from the dashboard (API Keys → Create Key, format sk_<keyId>_<secret>).

Pi agent

pi install npm:@hachibox/genai-otel

Config via env vars:

export GENAI_OTEL_TRACES_URL=https://api.hachibox.me/v1/traces
export GENAI_OTEL_API_KEY=<API_KEY>

Or via the credentials file instead of env vars:

mkdir -p ~/.pi/agent
cat > ~/.pi/agent/genai-otel.json <<'EOF'
{"tracesUrl": "https://api.hachibox.me/v1/traces", "apiKey": "<API_KEY>"}
EOF

Verify with pi list: @hachibox/genai-otel must appear. Run one turn in pi, then check the dashboard Overview for the trace.

Claude Code

claude plugin marketplace add langfuse/Claude-Observability-Plugin
claude plugin install langfuse-observability@langfuse-observability

Add to the project's .claude/settings.json:

{
  "env": {
    "TRACE_TO_LANGFUSE": "true",
    "LANGFUSE_PUBLIC_KEY": "<API_KEY keyId prefixed with sk_>",
    "LANGFUSE_SECRET_KEY": "<API_KEY>",
    "LANGFUSE_BASE_URL": "https://api.hachibox.me"
  }
}

The public key is the first 13 characters of API_KEY (i.e. sk_ plus the 10-character keyId, before the second _). Run one turn in Claude Code, then check the dashboard Overview for the trace.

Codex

codex plugin marketplace add langfuse/codex-observability-plugin
codex plugin add tracing@codex-observability-plugin

Enable the plugin in ~/.codex/config.toml (use <project>/.codex/config.toml for project-scoped setup):

[features]
plugin_hooks = true

[plugins."tracing@codex-observability-plugin"]
enabled = true

Credentials (env vars take precedence over the JSON file):

export TRACE_TO_LANGFUSE=true
export LANGFUSE_PUBLIC_KEY=<API_KEY keyId prefixed with sk_>
export LANGFUSE_SECRET_KEY=<API_KEY>
export LANGFUSE_BASE_URL=https://api.hachibox.me

Or store as JSON at ~/.codex/langfuse.json:

{
  "publicKey": "<API_KEY keyId prefixed with sk_>",
  "secretKey": "<API_KEY>",
  "baseUrl": "https://api.hachibox.me"
}

Run one turn in Codex, then check the dashboard Overview for the trace.

OpenTelemetry exporters (any OTLP/HTTP JSON pipeline)

export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://api.hachibox.me/v1/traces
export OTEL_EXPORTER_OTLP_HEADERS='Authorization=Basic <base64(public:API_KEY)>'
export OTEL_SERVICE_NAME=<your-service-name>

Basic-auth value is base64 of public:<API_KEY>. Set a distinct OTEL_SERVICE_NAME per project; it appears as the Service column in the dashboard Overview.

Troubleshooting

• No traces: confirm the plugin is loaded (pi list), the env vars are exported in the shell that launches the harness, and no stale PI_TRACING_ENABLED=false or GENAI_OTEL_TRACING_ENABLED=false override is set.
• 401 responses: re-check the API key and the base64 Basic value.