OpenLLMetry Writer 插桩:为 Writer AI 大模型调用接入 OpenTelemetry 可观测性
OpenLLMetry Writer 插桩:为 Writer AI 大模型调用接入 OpenTelemetry 可观测性
本文介绍 openllmetry 仓库中的 opentelemetry-instrumentation-writer 包:它能够对官方 writer-python(writerai)SDK 发出的 Chat 与 Completions 调用进行全自动插桩,以 OpenTelemetry Span、指标(Metrics)和日志事件(Events)三种形式采集 Writer 大模型应用的可观测性数据。读完本文,你将掌握该包的安装、一行代码接入、Span 属性与指标清单、流式响应追踪机制,以及通过环境变量控制隐私(是否记录 Prompt/Completion 原文)的完整方案。
一、包定位与适用场景
opentelemetry-instrumentation-writer 是 openllmetry 仓库中面向 Writer AI 的官方 Python SDK(writerai)专门设计的插桩库。它基于 OpenTelemetry 的 BaseInstrumentor 机制,在运行时对 writerai 客户端的核心端点方法进行包装(wrap),从而在不改动业务代码的前提下自动产生与每次 LLM 调用一一对应的追踪数据。
从源码的 WRAPPED_METHODS / WRAPPED_AMETHODS 定义(见 __init__.py)可以确认,本包覆盖两类端点:
| 端点 | 同步包装目标 | 异步包装目标 | Span 名称 | 请求类型 |
|---|---|---|---|---|
| Chat | writerai.resources.chat.ChatResource.chat |
AsyncChatResource.chat |
writerai.chat |
chat |
| Completions | writerai.resources.completions.CompletionsResource.create |
AsyncCompletionsResource.create |
writerai.completions |
completion |
同步与异步客户端(Writer 与 AsyncWriter)均在覆盖范围内。插桩声明的依赖版本区间为 writer-sdk >= 2.2.1, < 3(见 pyproject.toml),并且通过 opentelemetry_instrumentor entry point 暴露了 writer 这一自动插桩入口(pyproject.toml),可配合 OpenTelemetry 的自动插桩框架使用。
二、安装
使用 pip 直接安装即可:
pip install opentelemetry-instrumentation-writer
该包要求 Python 版本 >=3.10,<4,核心依赖包括:
opentelemetry-api>=1.38.0,<2opentelemetry-instrumentation>=0.59b0opentelemetry-semantic-conventions-ai>=0.5.1,<0.6.0(提供gen_ai.*/llm.*语义约定常量)opentelemetry-semantic-conventions>=0.63b1
上述依赖约束同样可见于 pyproject.toml。
三、快速开始:一行代码接入
在创建 Writer 客户端并发出请求之前,实例化并调用 WriterInstrumentor:
from opentelemetry.instrumentation.writer import WriterInstrumentor
WriterInstrumentor().instrument()
from writerai import Writer
client = Writer()
response = client.chat.chat(
model="palmyra-x4",
messages=[
{"role": "user", "content": "Tell me a joke about OpenTelemetry"},
],
temperature=0.7,
top_p=0.9,
max_tokens=340,
)
调用 .instrument() 之后,后续所有 client.chat.chat(...) 与 client.completions.create(...)(含异步形态 await client.chat.chat(...))都会被自动包装并生成追踪数据。
若要与项目中的其他 OpenTelemetry 初始化配合,可在 instrument() 时显式传入 Provider:
WriterInstrumentor().instrument(
tracer_provider=tracer_provider, # TracerProvider
meter_provider=meter_provider, # MeterProvider
logger_provider=logger_provider, # LoggerProvider(events 模式需要)
)
从 conftest.py 的测试夹具可以看到同样用法;测试中不传 logger_provider 时即运行在纯 span 的 legacy 模式。
3.1 插桩的工作原理
WriterInstrumentor 继承自 BaseInstrumentor(见 __init__.py),其 _instrument 方法做三件事:
- 通过
get_tracer/get_meter/get_logger获取对应 Provider 下的组件; - 依据
TRACELOOP_METRICS_ENABLED决定是否构建 4 个指标直方图; - 用
wrap_function_wrapper逐一包装WRAPPED_METHODS与WRAPPED_AMETHODS中列出的方法,并捕获ModuleNotFoundError——即使用户未安装writerai,插桩也不会导致导入失败。
_uninstrument 则通过 unwrap 还原被包装的方法,实现对称的卸载能力。
四、Span 结构与属性清单
每次调用会创建一个 SpanKind.CLIENT 的 Span,基础属性固定为(见 __init__.py):
{
SpanAttributes.LLM_SYSTEM: "writer", # gen_ai.system=writer
SpanAttributes.LLM_REQUEST_TYPE: "...", # llm.request.type=chat | completion
}
4.1 请求侧属性(输入)
set_model_input_attributes(span_utils.py)从调用参数中提取以下属性,属性常量定义见 语义约定包:
| Span 属性 | 来源参数 | 说明 |
|---|---|---|
gen_ai.request.model |
model |
请求的模型名,如 palmyra-x4 |
gen_ai.request.max_tokens |
max_tokens |
最大输出 token 数 |
gen_ai.request.temperature |
temperature |
采样温度 |
gen_ai.request.top_p |
top_p |
核采样概率 |
llm.chat.stop_sequences |
stop |
停止序列 |
llm.is_streaming |
stream |
是否为流式请求(默认 False) |
当 TRACELOOP_TRACE_CONTENT 开启(默认)时,set_input_attributes(span_utils.py)还会记录:
- 对 completions 请求:
gen_ai.prompt.0.role与gen_ai.prompt.0.content; - 对 chat 请求:按消息索引逐条记录
gen_ai.prompt.{i}.role与gen_ai.prompt.{i}.content,若消息携带tool_calls,还会记录gen_ai.prompt.{i}.tool_calls.{j}.id、name、arguments。
4.2 响应侧属性(输出)
set_model_response_attributes(span_utils.py)从响应对象的 usage 字段提取 token 统计:
gen_ai.response.model:实际响应的模型名llm.usage.total_tokens/llm.usage.completion_tokens/llm.usage.prompt_tokens- 当
usage.prompt_token_details.cached_tokens存在时,记录缓存读取 token 数(gen_ai.usage.cache_read.input_tokens)
set_response_attributes(span_utils.py)则在内容追踪开启时,为每个 choice 记录:
gen_ai.completion.{i}.finish_reason、role、content- 若包含工具调用:
gen_ai.completion.{i}.tool_calls.{j}.id、name、arguments
这些属性取值均在 test_chat.py 与 test_completions.py 中有逐项断言验证。
五、流式响应(Streaming)的追踪与聚合
流式请求返回的是 writerai._streaming.Stream / AsyncStream 生成器。本包无法在响应返回瞬间拿到完整结果,因此采用生成器包装 + 分块累加策略(见 __init__.py):
- 调用返回流对象后,不立即结束 Span,而是返回一个包装过的生成器;
- 消费方每取一个 chunk,
_update_accumulated_response就把增量合并进accumulated_response——包括content文本拼接、role、finish_reason、tool_calls的id/name/arguments累加(__init__.py); - 记录首 token 时间与末 token 时间,用于计算流式指标;
- 生成器耗尽后,在
finally中统一上报指标、写入响应属性、设置OK状态并结束 Span; - 若消费过程中抛异常,Span 状态置为
ERROR并向上抛出原始异常。
因此,流式响应必须被完整消费(遍历完),Span 才会结束并携带最终聚合结果,例如 gen_ai.completion.0.content 在流式场景下等于拼接后的完整文本,该行为在 test_writer_streaming_chat_legacy 等测试中验证(test_chat.py)。
六、自动采集的指标(Metrics)
默认情况下插桩会自动上报以下直方图指标(构建逻辑见 __init__.py):
| 指标名 | 单位 | 语义 |
|---|---|---|
gen_ai.client.token.usage |
token | 输入/输出 token 用量(通过 `gen_ai.token.type=input |
gen_ai.client.operation.duration |
s | 单次生成操作总耗时 |
gen_ai.server.time_to_first_token |
s | 流式首 token 耗时(TTFT) |
llm.chat_completions.streaming_time_to_generate |
s | 流式首 token 至完成耗时 |
这些指标的数据点统一携带 gen_ai.system=writer、gen_ai.response.model、llm.request.type 属性,流式指标额外带有 stream=true(相关断言见 test_metrics.py)。对于非流式调用,只上报 token usage 与 duration;流式调用则额外上报两个流式耗时指标,且满足 total_time == time_to_first_token + time_to_generate 的恒等关系。
可通过环境变量 TRACELOOP_METRICS_ENABLED 关闭指标采集:
TRACELOOP_METRICS_ENABLED=false
其判定逻辑为 (os.getenv("TRACELOOP_METRICS_ENABLED") or "true").lower() == "true"(__init__.py),即默认开启、显式设为 false 时关闭。
七、事件模式:从 Span 属性到 Log Events
WriterInstrumentor 构造参数 use_legacy_attributes(默认 True)控制两种数据输出模式:
- legacy 模式(默认):Prompt/Completion 原文写入 Span 属性,不产生日志事件;
- events 模式:
use_legacy_attributes=False时,输入输出通过 OpenTelemetry Logs API 以事件(gen_ai.*.message/gen_ai.choice)形式发射,Span 上不再写内容类属性,只保留模型名、token 用量等结构化信息。
事件模式由 should_emit_events() 判定(utils.py),具体发射逻辑在 event_emitter.py:
- 输入消息:按角色发射
gen_ai.user.message、gen_ai.assistant.message、gen_ai.tool.message、gen_ai.system.message;completions 的prompt参数归为gen_ai.user.message; - 输出选择:发射
gen_ai.choice,包含index、finish_reason、message与工具调用; - 所有事件带
gen_ai.system=writer属性(event_emitter.py)。
两种模式下事件数量与内容的差异,在测试中被精确断言(test_chat.py):legacy 模式日志数为 0,events 模式根据输入消息条数产生对应数量的 message 事件与 1 个 choice 事件。
八、隐私控制:TRACELOOP_TRACE_CONTENT
默认情况下,本插桩会把 Prompt、Completion 以及 Embedding 文本记录到 Span 属性中(README 原文说明),这为调试与评估输出质量提供了极大便利。但对话内容可能包含用户敏感数据,此时应关闭内容追踪以保护隐私,同时也能显著减小 Trace 体积。
关闭方式为设置环境变量:
TRACELOOP_TRACE_CONTENT=false
判定逻辑在 utils.py:
def should_send_prompts() -> bool:
return (
os.getenv(TRACELOOP_TRACE_CONTENT) or "true"
).lower() == "true" or context_api.get_value("override_enable_content_tracing")
也就是说:环境变量缺失或为 true 时记录内容;设为 false 时隐藏内容。此时:
- Span 属性中不再写入
gen_ai.prompt.*与gen_ai.completion.*内容,但gen_ai.request.model、token 用量等元数据仍保留; - 事件模式下,事件 body 中的
content字段会被删除,tool_calls的函数arguments也会被移除(event_emitter.py),测试中的*_with_no_content用例对此有完整验证(test_chat.py)。
九、初始化参数与其他配置
WriterInstrumentor 构造函数支持两个可选参数(__init__.py):
WriterInstrumentor(
exception_logger=None, # 自定义异常回调,插桩内部异常时调用
use_legacy_attributes=True, # False 时切换到事件模式
)
exception_logger:插桩内部处理 Span 属性、事件发射等步骤出现异常时(这些异常被dont_throw装饰器捕获并吞掉,避免影响业务调用),会回调此函数(utils.py);use_legacy_attributes:如上节所述切换输出模式,对应配置类Config的两个类属性(config.py)。
若同时设置了 TRACELOOP_METRICS_ENABLED=false 与 TRACELOOP_TRACE_CONTENT=false,Span 仍会记录模型名、请求参数与 token 用量等非内容元数据——两者分别控制"指标是否采集"与"内容是否落盘",互不冲突。
十、完整示例与测试参考
仓库中提供了可直接运行的完整示例 writer_example.py,演示了 Traceloop.init() 初始化、Writer 客户端创建、带 tools 的流式 Chat 调用、流式 chunk 的手动聚合以及工具结果回传的完整 Agent 流程,可与本文的插桩接入方式对照使用。
包内测试体系(基于 pytest + VCR 录制回放)覆盖了同步/异步、流式/非流式、多 choice、多工具调用、事件模式与指标采集等全部组合场景,可在 tests/test_chat.py、tests/test_completions.py、tests/test_metrics.py 中查看;测试所需的 Provider 装配方式见 tests/conftest.py。运行测试前需要在环境中设置 WRITER_API_KEY(conftest 中默认兜底为 test_api_key)。
十一、小结
opentelemetry-instrumentation-writer 让 Writer 大模型应用的可观测性接入成本低到"一行代码":插桩自动完成端点包装、Span 生成、流式聚合、指标上报与事件发射。在生产环境中,建议根据业务对数据合规的要求显式配置两个环境变量——TRACELOOP_TRACE_CONTENT(内容记录开关)与 TRACELOOP_METRICS_ENABLED(指标开关),在可观测性与隐私安全之间取得平衡。