# 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

```sh
pi install npm:@hachibox/genai-otel
```

Config via env vars:

```sh
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:

```sh
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

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

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

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

```sh
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):

```toml
[features]
plugin_hooks = true

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

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

```sh
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`:

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

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