OpenLLMetry 接入指南:用 OpenTelemetry 插桩 Anthropic SDK 实现 LLM 全链路可观测
OpenLLMetry 接入指南:用 OpenTelemetry 插桩 Anthropic SDK 实现 LLM 全链路可观测
导读
本指南讲解 openllmetry 仓库中的 opentelemetry-instrumentation-anthropic 插桩库:它基于 OpenTelemetry 语义约定自动追踪官方 Anthropic Python SDK 发送的 prompts 与 completions,把每次模型调用记录为 span,并输出 token 用量、延迟、结束原因等指标。读完本文你将掌握:如何安装并一行代码启用插桩、如何解读生成的 span 属性与事件、如何应对流式调用与隐私脱敏,以及如何通过源码理解其底层实现。
一、插桩库在 openllmetry 中的定位
openllmetry 是一个基于 OpenTelemetry 的开源 GenAI / LLM 可观测性方案。opentelemetry-instrumentation-anthropic 是其官方维护的 Anthropic 专用插桩包,作用是拦截官方 Anthropic Python SDK:它依赖 opentelemetry-api>=1.38.0、opentelemetry-instrumentation>=0.59b0 以及 opentelemetry-semantic-conventions-ai,并声明了 anthropic entry point,因此可被 opentelemetry-instrument CLI 自动发现。
二、安装
pip install opentelemetry-instrumentation-anthropic
该包要求 Python >=3.10,<4,插桩目标为 anthropic >= 0.3.11(定义于 __init__.py 的 _instruments)。仓库内还维护了基于 uv 的锁文件 uv.lock 供可复现安装使用;若使用 Traceloop SDK 接入,可参考 sample-app 中先 Traceloop.init(...) 再创建 Anthropic() 客户端的写法。
三、一行代码启用插桩
最小启用方式与官方 README 完全一致:
from opentelemetry.instrumentation.anthropic import AnthropicInstrumentor
AnthropicInstrumentor().instrument()
执行后,后续创建的 Anthropic 与 AsyncAnthropic 客户端发起的调用都会自动被插桩。仓库中的示例应用 anthropic_joke_example.py 展示了完整用法:在 Traceloop.init(app_name="sample-app", disable_batch=True) 之后调用 anthropic.messages.create(...),无需任何手工埋点。
如果你希望手动控制 TracerProvider / MeterProvider / LoggerProvider,可以像测试夹具(conftest.py)那样传入:
instrumentor = AnthropicInstrumentor(enrich_token_usage=True)
instrumentor.instrument(
tracer_provider=tracer_provider,
meter_provider=meter_provider,
)
# ... 运行你的代码 ...
instrumentor.uninstrument()
uninstrument() 会调用 unwrap 还原所有被包装的方法(见 __init__.py)。
四、底层原理:包装了哪些 SDK 方法
插桩通过 wrapt.wrap_function_wrapper 对 SDK 方法做 monkey-patch。从源码的 WRAPPED_METHODS / WRAPPED_AMETHODS 列表(__init__.py)可以看到,覆盖范围包括:
| 被包装对象 | 方法 | span 名称 |
|---|---|---|
anthropic.resources.completions.Completions |
create |
anthropic.completion |
anthropic.resources.messages.Messages |
create / stream |
anthropic.chat |
anthropic.resources.messages.AsyncMessages |
create / stream |
anthropic.chat |
anthropic.resources.beta.messages.messages.Messages(Beta 消息 API) |
create / stream |
anthropic.chat |
anthropic.lib.bedrock._beta_messages.Messages(Bedrock SDK) |
create / stream |
anthropic.chat |
两个值得注意的实现细节:
- 异步 stream 用同步包装器:
AsyncMessages.stream()返回的是AsyncMessageStreamManager(async context manager)而非协程,因此源码注释明确说明它必须用同步 wrapper 包装,否则async with client.messages.stream(...)会被破坏(__init__.py)。 - span 属性:每个 span 以
SpanKind.CLIENT创建,并固定写入gen_ai.provider.name = "anthropic"与gen_ai.operation.name(chat或text_completion),见_wrap/_awrap(__init__.py)。
五、Span 上会记录哪些数据
5.1 请求侧属性
aset_input_attributes(span_utils.py)会把以下请求参数写入 span:
gen_ai.request.model:模型名,如claude-3-opus-20240229gen_ai.request.max_tokens:max_tokens_to_sample或max_tokensgen_ai.request.temperature、gen_ai.request.top_pgen_ai.request.frequency_penalty、gen_ai.request.presence_penaltygen_ai.is_streaming:是否流式gen_ai.system_instructions:system 内容(JSON parts 数组)gen_ai.input.messages:消息列表,按 OTel GenAI 规范的parts结构输出gen_ai.tool.definitions:tools 定义(name / description / input_schema)gen_ai.request.structured_output_schema:当output_format为json_schema时输出 schema(对应 test_structured_outputs.py 的断言)
5.2 响应侧属性
set_response_attributes(span_utils.py)记录:
gen_ai.response.model、gen_ai.response.idgen_ai.usage.input_tokens、gen_ai.usage.output_tokens、gen_ai.usage.total_tokensgen_ai.response.finish_reasons:由 Anthropicstop_reason映射而来,映射表见 span_utils.py:end_turn/stop_sequence→stop,tool_use→tool_call,max_tokens→lengthgen_ai.output.messages:assistant 输出,包含text、reasoning(thinking 内容)、tool_call等 parts
5.3 Prompt Caching 专属属性
源码在 token 统计中专门处理了 Anthropic 的 prompt caching(__init__.py):
gen_ai.usage.cache_read.input_tokens:命中缓存的输入 tokengen_ai.usage.cache_creation.input_tokens:写入缓存的输入 token- 二者都会累加进
gen_ai.usage.input_tokens
test_prompt_caching.py 用连续两次相同请求验证:第一次 span 只有 cache_creation 而 cache_read == 0,第二次恰好相反,且两 span 的缓存 token 数相等。
5.4 结构化输出、Thinking 与图像
- 结构化输出:测试 test_structured_outputs.py 通过
client.beta.messages.create(..., betas=["structured-outputs-2025-11-13"], output_format={...})验证gen_ai.request.structured_output_schema被完整序列化。 - Thinking:测试 test_thinking.py 验证
thinking块被映射为{"type": "reasoning", "content": ...}part,且finish_reason == "stop"。 - 图像:base64 图像默认输出为
{"type": "blob", "modality": "image", ...};若配置了upload_base64_image回调,则上传后输出为{"type": "uri", ...}(见 span_utils.py)。
六、流式调用(Streaming)的处理
插桩对 messages.create(stream=True)、messages.stream(...) 以及异步流做了专门包装。核心类是 streaming.py 中的 AnthropicStream / AnthropicAsyncStream(基于 wrapt.ObjectProxy)以及 WrappedMessageStreamManager / WrappedAsyncMessageStreamManager。
关键行为:
- 迭代流时,每个事件被
_process_response_item聚合进complete_response(模型、id、usage、每个 content block 的 text / thinking / tool input 以及最终stop_reason)。 - Span 在流被完整消费后才结束:当迭代抛出
StopIteration/StopAsyncIteration时触发_complete_instrumentation,此时才写 token usage、时长直方图与输出消息(streaming.py)。 - 为兼容 SDK 辅助方法,
get_final_message、text_stream、until_done都被重定向到经过插桩的迭代路径(streaming.py),保证用户代码async for event in response或with client.messages.stream(...) as stream: stream.get_final_message()照常工作。
仓库示例 async_anthropic_joke_streaming.py 展示了 stream=True 配合 async for 消费 content_block_delta 的实际用法。
七、两种内容上报模式:Span 属性 vs 日志事件
这是本插桩最具迁移含义的配置点。AnthropicInstrumentor 构造函数中的 use_attributes(默认 True)决定内容如何上报;旧的 use_legacy_attributes 参数已被标记为 deprecated(__init__.py):
use_attributes=True(默认):prompt/completion 写入 span 属性gen_ai.input.messages/gen_ai.output.messages,这是当前 OTel GenAI 规范的做法。use_attributes=False(事件模式):改用 OpenTelemetry Logger 发出gen_ai.user.message、gen_ai.system.message、gen_ai.assistant.message、gen_ai.choice等日志事件。事件结构见 event_emitter.py 与 event_models.py,消息体(body)含content、role,choice 事件含index、finish_reason与可选的tool_calls。
测试 test_messages.py 对此做了对照验证:legacy 模式(use_legacy_attributes=True)下 span 携带 gen_ai.input.messages 且日志数为 0;事件模式下产生 2 条日志(user message 与 assistant choice)且 span 属性同样记录 token 用量。两个构造函数参数不能同时传入,否则抛出 TypeError。
八、隐私与内容脱敏:TRACELOOP_TRACE_CONTENT
这是 README 强调的重点,务必理解默认行为:
默认情况下,插桩会把 prompts、completions 记录到 span 属性中,以便清晰观察 LLM 应用的工作方式、便于调试与评估输出质量。但这些内容可能包含用户的高度敏感数据,且会显著增大 trace 体积。
关闭内容记录的官方方式:
TRACELOOP_TRACE_CONTENT=false
该环境变量的判定逻辑在 utils.py 的 should_send_prompts():读取 TRACELOOP_TRACE_CONTENT(默认 "true"),仅当值的小写形式等于 "true" 时才发送内容;同时它还会检查 context 中的 override_enable_content_tracing,允许在运行期通过 context 覆盖。
关闭后,span 仍保留模型名、token 用量、finish reason、请求参数等元数据,只是不再写入 gen_ai.input.messages / gen_ai.output.messages 等正文;事件模式下则从消息 body 中删除 content 与 tool 参数(见 event_emitter.py)。测试夹具 instrument_with_no_content(conftest.py)正是把该变量设为 "False" 来验证脱敏行为。
九、指标(Metrics)与运行开关
插桩同时创建四个 OpenTelemetry 指标(__init__.py):
| 指标名 | 类型 | 说明 |
|---|---|---|
gen_ai.client.token.usage |
Histogram(单位 token) | 输入/输出 token 用量 |
gen_ai.client.generation.choices |
Counter(单位 choice) | 每次调用返回的 choices 数量 |
gen_ai.client.operation.duration |
Histogram(单位 s) | GenAI 操作耗时 |
llm.anthropic.completion.exceptions |
Counter(单位 time) | 调用异常次数 |
这些指标均携带 gen_ai.provider.name、gen_ai.response.model 以及(可选)gen_ai.response.finish_reason 作为维度。新增环境变量 TRACELOOP_METRICS_ENABLED(默认 true,见 __init__.py)可整体关闭指标采集;关闭后直方图与计数器均为 None,插桩逻辑会自动跳过指标记录分支。
十、高级配置项一览
AnthropicInstrumentor 构造参数(对应 config.py 中的全局 Config):
enrich_token_usage=False:流式响应缺少 usage 时,是否调用anthropic.count_tokens估算 token(见 streaming.py)。exception_logger=None:插桩内部异常的回调,默认仅以 debug 级别记日志(dont_throw装饰器保证插桩失败绝不影响业务调用,utils.py)。get_common_metrics_attributes=lambda: {}:为所有指标附加公共维度的回调。upload_base64_image=None:base64 图像上传回调,签名(trace_id, span_id, image_name, base64_string),返回 URL;不配置时图像以 blob 形式直接落 span。use_attributes/use_legacy_attributes:见第七节,两者互斥。
十一、如何验证插桩是否生效
仓库的测试是最直观的验证样本,全部通过 pytest-recording + VCR cassettes(tests/cassettes)录制真实 API 响应,无需真实密钥即可离线运行:
- test_messages.py:断言 span 名为
anthropic.chat、输入输出消息结构与 token 数 - test_prompt_caching.py:验证缓存读写 token 属性
- test_thinking.py:验证 reasoning part 与 finish reason
- test_structured_outputs.py:验证结构化输出 schema
- test_completion.py:验证
anthropic.completionspan(Text Completions API) - test_bedrock_with_raw_response.py 与 test_semconv_compliance.py:分别验证 Bedrock 路径与语义约定常量一致性
语义约定的常量定义在 opentelemetry-semantic-conventions-ai,例如 gen_ai.usage.total_tokens、gen_ai.response.finish_reason 等项目约定属性。
十二、注意事项与限制
- 插桩目标版本为
anthropic >= 0.3.11;若某 SDK 方法在当前版本中不存在,包装失败会被静默忽略(except Exception: pass),不会中断程序。 - 关闭
TRACELOOP_TRACE_CONTENT只是不记录正文,token 用量、耗时等元数据指标仍然完整,这是做成本核算与延迟监控时的推荐组合。 - 仓库是只读镜像,安装与运行方式以
pip install与官方示例为准;如需本地调试测试,可在包目录下使用 uv/pytest 依 pyproject.toml 声明的依赖运行。