Control and observability

Observability with OpenTelemetry

Observability with OpenTelemetry 这一页讲的，就是 Observability with OpenTelemetry 这件事在 Claude Code 里到底怎么用。

页面信息

对应原页

页面性质

第三方中文解释页

使用建议

先看人话解释，再对照原页命令和代码

这页不是官方原文，而是顺着官方文档结构做的中文解释版。命令、参数、配置名这些硬东西尽量保留，解释部分则尽量讲成人能照着做的话。

如果你碰到特别敏感的配置、权限或企业环境差异，最好顺手点上面的“查看原始文档”再核一遍。

这一页先讲明白

这页主要讲 Observability with OpenTelemetry：Export traces, metrics, and events from the Agent SDK to your observability backend using OpenTelemetry.

你可以把它当成"Control and observability"这块里专门管这一摊事的说明书。

你可以把"Observability with OpenTelemetry"理解成 Control and observability 这一栏里的一把专门工具。这页不是让你背书，而是教你什么时候该把这把工具拿出来。

原文这页大多会按 How telemetry flows from the SDK、Enable telemetry export、Flush telemetry from short-lived calls、Read agent traces 这些环节往下讲。

翻成人话，大概就是：How telemetry flows from the SDK

第一，先别一上来全开全配。先按最小一步试通，确认没跑偏，再继续往下加。

第二，命令、配置名、参数名这些硬东西尽量保留原样。人话解释是帮你听懂，不是帮你改关键字。

第三，照着原文这几个环节挨个过：How telemetry flows from the SDK -> Enable telemetry export -> Flush telemetry from short-lived calls -> Read agent traces。像下地先看水路、再试机器、再正式开干，一步一步最稳。

关键片段

原页关键片段：Enable telemetry export

这一段要真抓重点，通常就抓下面这块原文。

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

OTEL_ENV = {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    # Required for traces, which are in beta. Metrics and log events do not need this.
    "CLAUDE_CODE_ENHANCED_TELEMETRY_BETA": "1",
    # Choose an exporter per signal. Use otlp for the SDK; see the Note below.
    "OTEL_TRACES_EXPORTER": "otlp",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    # Standard OTLP transport configuration.
    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://collector.example.com:4318",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer your-token",
}


async def main():
    options = ClaudeAgentOptions(env=OTEL_ENV)
    async for message in query(
        prompt="List the files in this directory", options=options
    ):
        print(message)


asyncio.run(main())

关键片段

原页关键片段：Flush telemetry from short-lived calls

"Flush telemetry from short-lived calls"这一段里最要紧的原始写法在下面，先看它怎么落地。

OTEL_ENV = {
    # ... exporter configuration from the previous example ...
    "OTEL_METRIC_EXPORT_INTERVAL": "1000",
    "OTEL_LOGS_EXPORT_INTERVAL": "1000",
    "OTEL_TRACES_EXPORT_INTERVAL": "1000",
}

关键片段

原页关键片段：Tag telemetry from your agent

"Tag telemetry from your agent"这一段里最要紧的原始写法在下面，先看它怎么落地。

options = ClaudeAgentOptions(
    env={
        # ... exporter configuration ...
        "OTEL_SERVICE_NAME": "support-triage-agent",
        "OTEL_RESOURCE_ATTRIBUTES": "service.version=1.4.0,deployment.environment=production",
    },
)

关键片段

原页关键片段：Attribute actions to your end users

这一段要真抓重点，通常就抓下面这块原文。

from urllib.parse import quote

options = ClaudeAgentOptions(
    env={
        # ... exporter configuration ...
        "OTEL_RESOURCE_ATTRIBUTES": f"enduser.id={quote(request.user_id)},tenant.id={quote(request.tenant_id)}",
    },
)

预留广告位

正文中段响应式广告 等你后面真接 AdSense，这里再放正式广告。

Documentation Index

这里不是让你背"Documentation Index"这个词，而是让你看它真干活时怎么使。

看这段时要特别盯工具和权限边界，别为了省事一把全开。

How telemetry flows from the SDK

别把这段只当成标题看，它其实是在给"How telemetry flows from the SDK"划边界。

看这段时要特别盯工具和权限边界，别为了省事一把全开。

Enable telemetry export

这里讲怎么把某个开关拧对。重点不是概念，而是你该在哪儿改、改完怎么确认生效。

看这段时要特别盯工具和权限边界，别为了省事一把全开。

关键片段

Enable telemetry export

这一段要真抓重点，通常就抓下面这块原文。

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

OTEL_ENV = {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    # Required for traces, which are in beta. Metrics and log events do not need this.
    "CLAUDE_CODE_ENHANCED_TELEMETRY_BETA": "1",
    # Choose an exporter per signal. Use otlp for the SDK; see the Note below.
    "OTEL_TRACES_EXPORTER": "otlp",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    # Standard OTLP transport configuration.
    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://collector.example.com:4318",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer your-token",
}


async def main():
    options = ClaudeAgentOptions(env=OTEL_ENV)
    async for message in query(
        prompt="List the files in this directory", options=options
    ):
        print(message)


asyncio.run(main())

Flush telemetry from short-lived calls

这一段不只是挂个标题，它是在说明"Flush telemetry from short-lived calls"这一块到底负责什么。

关键片段

Flush telemetry from short-lived calls

"Flush telemetry from short-lived calls"这一段里最要紧的原始写法在下面，先看它怎么落地。

OTEL_ENV = {
    # ... exporter configuration from the previous example ...
    "OTEL_METRIC_EXPORT_INTERVAL": "1000",
    "OTEL_LOGS_EXPORT_INTERVAL": "1000",
    "OTEL_TRACES_EXPORT_INTERVAL": "1000",
}

Read agent traces

这一块主要是在说"Read agent traces"真到手上该怎么用，哪里最容易踩坑。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

Link traces to your application

这里主要是在交代"Link traces to your application"这一块会碰到哪些事。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

Tag telemetry from your agent

这一块主要是在说"Tag telemetry from your agent"真到手上该怎么用，哪里最容易踩坑。

关键片段

Tag telemetry from your agent

"Tag telemetry from your agent"这一段里最要紧的原始写法在下面，先看它怎么落地。

options = ClaudeAgentOptions(
    env={
        # ... exporter configuration ...
        "OTEL_SERVICE_NAME": "support-triage-agent",
        "OTEL_RESOURCE_ATTRIBUTES": "service.version=1.4.0,deployment.environment=production",
    },
)

Attribute actions to your end users

看到这里，就别靠猜了，字段、格式和写法都得按说明来。

这里还牵扯作用域，意思就是这条规则到底管当前项目、你个人，还是只管这一趟会话。

关键片段

Attribute actions to your end users

这一段要真抓重点，通常就抓下面这块原文。

from urllib.parse import quote

options = ClaudeAgentOptions(
    env={
        # ... exporter configuration ...
        "OTEL_RESOURCE_ATTRIBUTES": f"enduser.id={quote(request.user_id)},tenant.id={quote(request.tenant_id)}",
    },
)

Control sensitive data in exports

这里讲的是收放和管理，不只是"能不能用"，而是"怎么管住、怎么不乱"。

看这段时要特别盯工具和权限边界，别为了省事一把全开。

第 1 步：Enable telemetry export

这一段要真抓重点，通常就抓下面这块原文。

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

OTEL_ENV = {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    # Required for traces, which are in beta. Metrics and log events do not need this.
    "CLAUDE_CODE_ENHANCED_TELEMETRY_BETA": "1",
    # Choose an exporter per signal. Use otlp for the SDK; see the Note below.
    "OTEL_TRACES_EXPORTER": "otlp",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    # Standard OTLP transport configuration.
    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "http://collector.example.com:4318",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer your-token",
}


async def main():
    options = ClaudeAgentOptions(env=OTEL_ENV)
    async for message in query(
        prompt="List the files in this directory", options=options
    ):
        print(message)


asyncio.run(main())

关键片段

第 2 步：Flush telemetry from short-lived calls

"Flush telemetry from short-lived calls"这一段里最要紧的原始写法在下面，先看它怎么落地。

OTEL_ENV = {
    # ... exporter configuration from the previous example ...
    "OTEL_METRIC_EXPORT_INTERVAL": "1000",
    "OTEL_LOGS_EXPORT_INTERVAL": "1000",
    "OTEL_TRACES_EXPORT_INTERVAL": "1000",
}

关键片段

第 3 步：Tag telemetry from your agent

"Tag telemetry from your agent"这一段里最要紧的原始写法在下面，先看它怎么落地。

options = ClaudeAgentOptions(
    env={
        # ... exporter configuration ...
        "OTEL_SERVICE_NAME": "support-triage-agent",
        "OTEL_RESOURCE_ATTRIBUTES": "service.version=1.4.0,deployment.environment=production",
    },
)

关键片段

第 4 步：Attribute actions to your end users

这一段要真抓重点，通常就抓下面这块原文。

from urllib.parse import quote

options = ClaudeAgentOptions(
    env={
        # ... exporter configuration ...
        "OTEL_RESOURCE_ATTRIBUTES": f"enduser.id={quote(request.user_id)},tenant.id={quote(request.tenant_id)}",
    },
)

一眼看懂这一页

先把这页到底在讲什么看明白，再去碰具体命令和配置，最不容易绕晕。

Observability with OpenTelemetry
   |
   v
这是 Control and observability 里的一摊要紧活
   |
   v
先弄懂，再下手

文末提醒

这站会按官方 docs 的导航和内容变化继续重生成，原站加页、删页、改页时，这里会跟着更新。

人话解释会尽量顺着原页往下讲，但命令、参数名、配置名这些硬东西还是保留原样，免得你抄过去跑不起来。