OpenLLMetry 接入指南:用 OpenTelemetry 插桩 Anthropic SDK 实现 LLM 全链路可观测

原创2026-10-14 10:05:011,730 阅读
文章标签:LLMOps可观测性

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

两个值得注意的实现细节:

  1. 异步 stream 用同步包装器:AsyncMessages.stream() 返回的是 AsyncMessageStreamManager(async context manager)而非协程,因此源码注释明确说明它必须用同步 wrapper 包装,否则 async with client.messages.stream(...) 会被破坏(__init__.py)。
  2. 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-20240229
  • gen_ai.request.max_tokens:max_tokens_to_sample 或 max_tokens
  • gen_ai.request.temperature、gen_ai.request.top_p
  • gen_ai.request.frequency_penalty、gen_ai.request.presence_penalty
  • gen_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.id
  • gen_ai.usage.input_tokens、gen_ai.usage.output_tokens、gen_ai.usage.total_tokens
  • gen_ai.response.finish_reasons:由 Anthropic stop_reason 映射而来,映射表见 span_utils.py:end_turn/stop_sequence → stop,tool_use → tool_call,max_tokens → length
  • gen_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:命中缓存的输入 token
  • gen_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 响应,无需真实密钥即可离线运行:

语义约定的常量定义在 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 声明的依赖运行。
登录后查看全文
openllmetry