634650dd25
Add metrics capabilities to Codex. The `README.md` is up to date. This will not be merged with the metrics before this PR of course: https://github.com/openai/codex/pull/8350
48 lines
3.4 KiB
Markdown
48 lines
3.4 KiB
Markdown
# Codex Telemetry
|
|
|
|
## Config
|
|
|
|
**TODO(jif)**: add the config and document it
|
|
|
|
## Tracing
|
|
|
|
Codex can export OpenTelemetry **log events**, **trace spans**, and **metrics**
|
|
when OTEL exporters are configured in `config.toml` (`[otel]`).
|
|
By default, exporters are disabled and nothing is sent.
|
|
|
|
## Feedback
|
|
|
|
Feedback is sent only when you run `/feedback` and confirm. The report includes
|
|
the selected category and optional note; if you opt in to include logs, Codex
|
|
attaches the most recent in-memory logs for the session (up to ~4 MiB).
|
|
|
|
## Metrics
|
|
|
|
This section list all the metrics exported by Codex when locally installed.
|
|
|
|
### Global context (applies to every event/metric)
|
|
|
|
- `surface`: `cli` | `vscode` | `exec` | `mcp` | `subagent_*` (from `SessionSource`).
|
|
- `version`: binary version.
|
|
- `auth_mode`: `swic` (AuthMode::ChatGPT) | `api` (AuthMode::ApiKey) | `unknown`.
|
|
- `model`: name of the model used.
|
|
|
|
## Metrics catalog
|
|
|
|
Each metric includes the required fields plus the global context above.
|
|
|
|
| Metric | Type | Fields | Description |
|
|
| ------------------------- | --------- | ------------------------------------- | ------------------------------------------------------------------------------- |
|
|
| `approval.requested` | counter | `tool`, `approved` | Tool approval request result (`approved`: `yes` or `no`). |
|
|
| `auth.completed` | counter | `status` | Authentication completed (only for ChatGPT authentication). |
|
|
| `conversation.compact` | counter | `status`, `number` | Compaction event including the status and the compaction number in the session. |
|
|
| `conversation.turn.count` | counter | `role` | User/assistant turns per session. |
|
|
| `feature.duration_ms` | histogram | `feature`, `status` | End-to-end feature latency. |
|
|
| `feature.used` | counter | `feature` | Feature usage through `/` (e.g., `/undo`, `/review`, ...). |
|
|
| `features.state` | counter | `key`, `value` | Feature values that differ from defaults (emit one row per non-default). |
|
|
| `mcp.call` | counter | `status` | MCP tool invocation result (`ok` or error string). |
|
|
| `model.call.duration_ms` | histogram | `provider`, `status`, `attempt` | Model API request duration. |
|
|
| `session.started` | counter | `is_git` | New session created. |
|
|
| `tool.call` | counter | `tool`, `status` | Tool invocation result (`ok` or error string). |
|
|
| `tool.call.duration_ms` | histogram | `tool`, `status` | Tool execution time. |
|
|
| `user.feedback.submitted` | counter | `category`, `include_logs`, `success` | Feedback submission via `/feedback`. |
|