Monitoring changedmonitoring-usage
Nearest release: v2.1.305, published an hour after upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 20 Oct 2026 18:25 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 20 Oct 2026 18:37 UTC.
Upstream edited
Recorded here
Lines+38added
Lines−44removed
From line
4
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits60to this page, all time
The whole hunk
from line 4, old and new numbered
/
from line 4
44
55Track Claude Code usage, costs, and tool activity across your organization by exporting telemetry data through OpenTelemetry (OTel). Claude Code exports metrics as time series data via the standard metrics protocol, events via the logs/events protocol, and optionally [distributed traces via OpenTelemetry](#traces-beta).
66
7<Note>
8 For the Claude API or Managed Agents, see [OpenTelemetry for the Claude API](https://platform.claude.com/docs/en/manage-claude/opentelemetry).
9</Note>
7> [!NOTE]
8>
9> For the Claude API or Managed Agents, see [OpenTelemetry for the Claude API](https://platform.claude.com/docs/en/manage-claude/opentelemetry).
1010
1111## Quick start
1212
from line 274
274274| `skill_name` | Skill name for the Skill tool | `OTEL_LOG_TOOL_DETAILS` |
275275| `subagent_type` | Subagent type for the Agent tool or legacy Task tool | `OTEL_LOG_TOOL_DETAILS` |
276276
277<span id="tool-output-span-event" />**`tool.output` span event on `claude_code.tool`**
277**`tool.output` span event on `claude_code.tool`**
278278
279279If you set `OTEL_LOG_TOOL_CONTENT=1`, Read and Bash calls can record a `tool.output` span event on the `claude_code.tool` span. Edit and Write calls record one only when you also set `OTEL_LOG_TOOL_DETAILS=1`. That variable isn't scoped to those two tools, so check its [row in the configuration table](#common-configuration-variables) for the arguments it adds elsewhere.
280280
from line 338
338338| `num_non_blocking_error` | Count of hooks that failed without blocking | |
339339| `num_cancelled` | Count of hooks cancelled before completion | |
340340
341<span id="new-context-gates" />
342
343341**Content attributes under detailed beta tracing**
344342
345<Note>
346 Additional content-bearing attributes such as `new_context`, `system_reminders`, `system_prompt_preview`, `user_system_prompt`, `tool_input`, and `response.model_output` are emitted only when detailed beta tracing is active. They are not part of the stable span schema.
347</Note>
343> [!NOTE]
344>
345> Additional content-bearing attributes such as `new_context`, `system_reminders`, `system_prompt_preview`, `user_system_prompt`, `tool_input`, and `response.model_output` are emitted only when detailed beta tracing is active. They are not part of the stable span schema.
348346
349347These attributes appear on the spans below, and `Gated by` names the variable an attribute needs on top of detailed beta tracing. Values longer than the content limit (60 KB by default) are truncated.
350348
from line 416
418416
419417Each custom key becomes a label on every metric series, so high-cardinality values increase storage cost in your metrics backend. To send custom attributes in the resource block only and omit them from datapoint labels, set `OTEL_METRICS_INCLUDE_RESOURCE_ATTRIBUTES=false`. See [Metrics cardinality control](#metrics-cardinality-control).
420418
421<Warning>
422 The `OTEL_RESOURCE_ATTRIBUTES` environment variable uses comma-separated key=value pairs with strict formatting requirements:
419> [!WARNING]
420>
421> The `OTEL_RESOURCE_ATTRIBUTES` environment variable uses comma-separated key=value pairs with strict formatting requirements:
422>
423> * **No spaces allowed**: values can't contain spaces. For example, `user.organizationName=My Company` is invalid
424> * **Format**: must be comma-separated key=value pairs: `key1=value1,key2=value2`
425> * **Allowed characters**: only US-ASCII characters excluding control characters, whitespace, double quotes, commas, semicolons, and backslashes
426> * **Special characters**: characters outside the allowed range must be percent-encoded
427>
428> For a value that would need a space, use underscores or camelCase instead. The following examples set `org.name` with each form:
429>
430> ```bash theme={null}
431> export OTEL_RESOURCE_ATTRIBUTES="org.name=Johns_Organization"
432> export OTEL_RESOURCE_ATTRIBUTES="org.name=JohnsOrganization"
433> ```
434>
435> You can percent-encode any character, not only the excluded ones. This example encodes both the space and the apostrophe:
436>
437> ```bash theme={null}
438> export OTEL_RESOURCE_ATTRIBUTES="org.name=John%27s%20Organization"
439> ```
440>
441> Wrapping values in quotes doesn't escape spaces. For example, `org.name="My Company"` results in the literal value `"My Company"` with the quotes included, not `My Company`.
423442
424 * **No spaces allowed**: values can't contain spaces. For example, `user.organizationName=My Company` is invalid
425 * **Format**: must be comma-separated key=value pairs: `key1=value1,key2=value2`
426 * **Allowed characters**: only US-ASCII characters excluding control characters, whitespace, double quotes, commas, semicolons, and backslashes
427 * **Special characters**: characters outside the allowed range must be percent-encoded
428
429 For a value that would need a space, use underscores or camelCase instead. The following examples set `org.name` with each form:
430
431 ```bash theme={null}
432 export OTEL_RESOURCE_ATTRIBUTES="org.name=Johns_Organization"
433 export OTEL_RESOURCE_ATTRIBUTES="org.name=JohnsOrganization"
434 ```
435
436 You can percent-encode any character, not only the excluded ones. This example encodes both the space and the apostrophe:
437
438 ```bash theme={null}
439 export OTEL_RESOURCE_ATTRIBUTES="org.name=John%27s%20Organization"
440 ```
441
442 Wrapping values in quotes doesn't escape spaces. For example, `org.name="My Company"` results in the literal value `"My Company"` with the quotes included, not `My Company`.
443</Warning>
444
445443### Attribute telemetry to Desktop SSH sessions
446444
447445To see which remote machine a [Desktop SSH session](/docs/en/desktop#ssh-sessions) ran on, name each machine in a custom attribute. Metrics and events don't name the machine a session ran on.
from line 589
591589
592590In sessions signed in to a [Claude apps gateway](/docs/en/claude-apps-gateway) through `/login`, the CLI stamps exports with the authenticated identity: `user.id` is the IdP subject, `user.email` is the signed-in email, and `user.groups` carries IdP group membership as a comma-separated string. Each export also carries `identity.source: gateway-oidc`. The gateway identity is applied last, so `user.*` and `identity.*` keys set through `OTEL_RESOURCE_ATTRIBUTES` are ignored on those sessions.
593591
594<Note>
595 Events that Claude Code logs before a developer signs in don't carry the gateway identity. When Claude Code opens a session signed out of the gateway, for example after [the gateway ends the sign-in](/docs/en/errors#cloud-gateway-session-expired), the startup events logged before sign-in carry the anonymous `user.id` and no `identity.source`. These include [`managed_settings_resolved`](#managed-settings-resolved-event), [`plugin_loaded`](#plugin-loaded-event), and [`mcp_server_connection`](#mcp-server-connection-event).
596</Note>
592> [!NOTE]
593>
594> Events that Claude Code logs before a developer signs in don't carry the gateway identity. When Claude Code opens a session signed out of the gateway, for example after [the gateway ends the sign-in](/docs/en/errors#cloud-gateway-session-expired), the startup events logged before sign-in carry the anonymous `user.id` and no `identity.source`. These include [`managed_settings_resolved`](#managed-settings-resolved-event), [`plugin_loaded`](#plugin-loaded-event), and [`mcp_server_connection`](#mcp-server-connection-event).
597595
598596For the identity attributes on Claude Desktop and Cowork sessions that connect through a gateway, see the [gateway `telemetry` reference](/docs/en/claude-apps-gateway-config#telemetry).
599597
from line 1016
10181016 * For Skill tool: includes `skill_name`
10191017 * For Agent tool or legacy Task tool: includes `subagent_type`
10201018
1019If you lower the OpenTelemetry SDK's `OTEL_LOGRECORD_ATTRIBUTE_COUNT_LIMIT` below the number of attributes on a `tool_decision` event, the SDK drops the attributes that Claude Code set last. The SDK drops `permission_mode` first, `classifier_category` second, and `classifier_verdict` third, and drops the event's other attributes only after those three. This ordering requires Claude Code v2.1.302 or later.
1020
10211021#### Permission mode changed event
10221022
10231023Logged when the permission mode changes, for example from `Shift+Tab` cycling, exiting plan mode, or an auto mode gate check.
from line 1447
14471447* Identifying high-usage sessions for optimization
14481448* Attributing spend to specific skills, plugins, or subagent types via the `skill.name`, `plugin.name`, and `agent.name` attributes
14491449
1450<Note>
1451 Cost metrics are approximations. For official billing data, refer to your API provider (Claude Console, Amazon Bedrock, or Google Cloud's Agent Platform).
1452</Note>
1450> [!NOTE]
1451>
1452> Cost metrics are approximations. For official billing data, refer to your API provider (Claude Console, Amazon Bedrock, or Google Cloud's Agent Platform).
14531453
14541454Claude Code counts each streaming response toward the cost and token metrics exactly once, including when a gateway or proxy behind `ANTHROPIC_BASE_URL` streams usage progressively across multiple frames.
14551455
from line 1624
16241624
16251625Your choice of metrics, logs, and traces backends determines the types of analyses you can perform:
16261626
1627<span id="for-metrics" />
1628
16291627### Backends for metrics
16301628
16311629* **Time series databases**: Rate calculations, aggregated metrics
from line 1630
16321630* **Columnar stores**: Complex queries, unique user analysis
16331631* **Full-featured observability platforms**: Advanced querying, visualization, alerting
16341632
1635<span id="for-events/logs" />
1636
16371633### Backends for events and logs
16381634
16391635* **Log aggregation systems**: Full-text search, log analysis
16401636* **Columnar stores**: Structured event analysis
16411637* **Full-featured observability platforms**: Correlation between metrics and events
1642
1643<span id="for-traces" />
16441638
16451639### Backends for traces
16461640
No line in this hunk matches that.