OpenLLMetry Writer 插桩:为 Writer AI 大模型调用接入 OpenTelemetry 可观测性

原创2026-10-14 17:52:311,994 阅读
文章标签:LLMOps可观测性

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,<2
  • opentelemetry-instrumentation>=0.59b0
  • opentelemetry-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 方法做三件事:

  1. 通过 get_tracer / get_meter / get_logger 获取对应 Provider 下的组件;
  2. 依据 TRACELOOP_METRICS_ENABLED 决定是否构建 4 个指标直方图;
  3. 用 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):

  1. 调用返回流对象后,不立即结束 Span,而是返回一个包装过的生成器;
  2. 消费方每取一个 chunk,_update_accumulated_response 就把增量合并进 accumulated_response——包括 content 文本拼接、role、finish_reason、tool_calls 的 id/name/arguments 累加(__init__.py);
  3. 记录首 token 时间与末 token 时间,用于计算流式指标;
  4. 生成器耗尽后,在 finally 中统一上报指标、写入响应属性、设置 OK 状态并结束 Span;
  5. 若消费过程中抛异常,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(指标开关),在可观测性与隐私安全之间取得平衡。

登录后查看全文
openllmetry