Ingest OpenTelemetry

txtop includes an experimental OTLP/HTTP receiver for logs, traces, and metrics. Recognized usage events join the main timeline; other valid records remain in raw intake for diagnostics and future mappers.

The receiver flags and mapping contract may change within 1.x.

Start the receiver

txtop up --otlp-http --otlp-http-listen 127.0.0.1:4318
txtop status

The receiver accepts OTLP/HTTP at /v1/logs, /v1/traces, and /v1/metrics. It does not provide TLS or authentication. Keep it on loopback unless a trusted reverse proxy protects the public endpoint.

Connect Claude Code

Claude Code API-request logs carry per-request usage, so traces and metrics are not required for txtop:

export CLAUDE_CODE_ENABLE_TELEMETRY=1
export OTEL_METRICS_EXPORTER=none
export OTEL_LOGS_EXPORTER=otlp
export OTEL_TRACES_EXPORTER=none
export OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318
export OTEL_EXPORTER_OTLP_PROTOCOL=http/protobuf
claude

Put the same values under env in .claude/settings.local.json for one project, .claude/settings.json for a committed team setting, or ~/.claude/settings.json for the machine.

Claude Code omits prompt and tool content by default. Leave OTEL_LOG_USER_PROMPTS, OTEL_LOG_TOOL_DETAILS, and raw-body logging disabled unless the local database is approved to store that material.

Connect Codex

Add this to ~/.codex/config.toml:

[otel]
environment = "dev"
exporter = { "otlp-http" = { endpoint = "http://127.0.0.1:4318/v1/logs", protocol = "binary" } }
trace_exporter = "none"
metrics_exporter = "none"
log_user_prompt = false

txtop maps legacy codex.api_request logs and current codex.sse_event completion logs. Set log_user_prompt = true only when raw prompts may be stored locally.

Connect Gemini CLI

Add this to .gemini/settings.json or the applicable Gemini CLI settings file:

{
  "telemetry": {
    "enabled": true,
    "target": "local",
    "otlpEndpoint": "http://127.0.0.1:4318",
    "otlpProtocol": "http",
    "logPrompts": false
  }
}

Gemini CLI enables prompt logging by default, so keep logPrompts false unless prompt storage is intentional.

Connect OpenRouter or another client

OpenRouter needs a public HTTPS receiver; follow connect OpenRouter telemetry. Other clients can send standard OTLP/HTTP to the three signal endpoints. Valid but unknown records are retained without contributing to usage totals.

Supported usage mappings

• Claude Code claude_code.api_request logs and supported delta metrics
• Codex codex.api_request and codex.sse_event completion logs
• Gemini CLI gemini_cli.api_response logs
• OpenRouter traces with GenAI token-usage attributes

Cumulative metrics are stored but do not contribute to usage unless a mapper can compute a safe delta. When local logs and OTEL describe the same request, source-specific correlation and preference avoid double counting.

Verify ingest

txtop status
txtop db doctor
txtop db events --last 20

db doctor reports source successes, decode errors, and projector state. Exporter failures should not stop Claude Code, Codex, or Gemini CLI itself.

Configuration details change upstream. Check the current official references for Claude Code monitoring, Codex configuration, and Gemini CLI telemetry.