用 OpenTelemetry 追踪 Amazon SageMaker 推理调用:openllmetry SageMaker 插桩实践指南

原创2026-10-14 12:15:571,371 阅读
文章标签:LLMOps可观测性

用 OpenTelemetry 追踪 Amazon SageMaker 推理调用:openllmetry SageMaker 插桩实践指南

本指南围绕 openllmetry 仓库中的 opentelemetry-instrumentation-sagemaker 包展开,讲解如何对通过 Boto3 调用 Amazon SageMaker 端点(包括流式与非流式推理)的 LLM/GenAI 应用自动生成 OpenTelemetry Span 与可观测数据。读完本文,你将掌握该插桩库的安装方式、最小接入代码、隐私开关 TRACELOOP_TRACE_CONTENT 的正确用法,以及它内部的埋点机制、属性命名和错误处理行为,从而将 SageMaker 推理链路无缝接入基于 OpenTelemetry 的可观测平台。

一、这个插桩库解决什么问题

opentelemetry-instrumentation-sagemaker 是 openllmetry 项目中专门面向 Amazon SageMaker 的 OpenTelemetry 插桩组件。它的核心定位在 README.md 中写明:对部署在 SageMaker 上、并通过 Boto3 发起调用的任意模型进行链路追踪。它并不要求模型类型是自建还是托管,也不限定模型框架——只要是经由 sagemaker-runtime 服务调用的端点,都会被自动观测。

与仓库中其他插桩包(如 opentelemetry-instrumentation-openai、opentelemetry-instrumentation-bedrock 等)相比,SageMaker 插桩的特殊之处在于:

  • 它拦截的是 AWS SDK 层(Boto3/Botocore 的客户端创建),而不是某个模型供应商的 SDK;
  • 它覆盖两个关键 API:InvokeEndpoint(同步推理)与 InvokeEndpointWithResponseStream(流式推理);
  • 它默认把请求体(prompt)与响应体(生成内容)写入 span 属性,并提供环境变量级别的隐私开关。

二、安装与依赖环境

安装命令与包版本见 pyproject.toml:

pip install opentelemetry-instrumentation-sagemaker

安装该包时需要注意的运行时前提:

  • Python 版本要求 >=3.10,<4;
  • 依赖 opentelemetry-api>=1.38.0,<2、opentelemetry-instrumentation>=0.59b0,以及语义约定包 opentelemetry-semantic-conventions-ai>=0.5.1,<0.6.0;
  • 被插桩的目标库是 Boto3,pyproject 的 instruments 可选依赖声明为 boto3,而源码 init.py 中 _instruments = ("boto3 >= 1.28.57",) 明确了最低版本约束;
  • 该包注册了标准 entry point sagemaker,因此也支持通过 opentelemetry-instrument 命令行自动加载(见 pyproject 中 [project.entry-points."opentelemetry_instrumentor"] 一节)。

三、最小接入示例

按 README.md 的示例,接入只需要两行:

from opentelemetry.instrumentation.sagemaker import SageMakerInstrumentor

SageMakerInstrumentor().instrument()

在这之后,任何通过 Boto3 创建的 sagemaker-runtime 客户端都会自动被插桩。一个完整的调用场景如下:

import boto3
from opentelemetry.instrumentation.sagemaker import SageMakerInstrumentor

SageMakerInstrumentor().instrument()

smrt = boto3.client(
    service_name="sagemaker-runtime",
    region_name="us-east-1",
)

# 非流式推理:自动生成 span "sagemaker.completion"
response = smrt.invoke_endpoint(
    EndpointName="my-llama2-endpoint",
    Body='{"inputs": "What should I do with a llama in my garden?",
           "parameters": {"temperature": 0.1, "top_p": 0.9, "max_new_tokens": 128}}',
    ContentType="application/json",
)
print(response["Body"].read())

# 流式推理:同样自动生成 span
resp_stream = smrt.invoke_endpoint_with_response_stream(
    EndpointName="my-llama2-endpoint",
    Body='{"inputs": "Tell me a joke"}',
    ContentType="application/json",
)
for event in resp_stream["Body"]:
    print(event)

注意:插桩默认使用全局 TracerProvider 与 LoggerProvider。如果需要显式传入 provider(例如在测试或服务化场景中),可以在 instrument() 时通过 tracer_provider 与 logger_provider 参数指定,这与 conftest.py 中的 fixture 用法一致:

SageMakerInstrumentor().instrument(
    tracer_provider=tracer_provider,
    logger_provider=logger_provider,
)

四、工作原理:从 Boto3 调用到 Span 的完整链路

4.1 拦截点:客户端创建而非方法调用

从源码 init.py 可以看到,插桩并不直接包装 invoke_endpoint,而是先包装客户端工厂方法:

WRAPPED_METHODS = [
    {"package": "botocore.client", "object": "ClientCreator", "method": "create_client"},
    {"package": "botocore.session", "object": "Session", "method": "create_client"},
]

在 _wrap 中,只有当 kwargs.get("service_name") == "sagemaker-runtime" 时才会把 invoke_endpoint 与 invoke_endpoint_with_response_stream 替换为插桩版本,其他 AWS 服务(如 S3、DynamoDB 等)不会被影响。这种设计让插桩对业务代码完全透明——你不需要修改任何调用代码。

4.2 Span 的创建与命名

无论同步还是流式,插桩都会创建一个名为 sagemaker.completion、类型为 SpanKind.CLIENT 的 span。同步路径使用 start_as_current_span 上下文管理器;流式路径则先 start_span,等整个响应流消费完毕后再结束 span(见 _handle_stream_call 中的回调逻辑)。

Span 上记录的语义属性由 span_utils.py 写入:

属性 来源 说明
gen_ai.request.model kwargs["EndpointName"] 标记本次调用使用的 SageMaker 端点名,遵循 OpenTelemetry GenAI 语义约定
traceloop.entity.input 请求体 kwargs["Body"](先尝试 JSON 解析) 输入内容,即 prompt
traceloop.entity.output 响应体(先尝试 JSON 解析) 输出内容,即模型生成结果

请求体与响应体都会先经过 _try_parse_json 做 JSON 解析,解析失败时回退为原始字符串;随后统一 json.dumps 序列化后写入 span 属性,保证属性值形态一致、便于在 UI 中检索。

4.3 流式响应的两个关键包装器

流式推理之所以复杂,是因为 span 属性需要等整个流读完才能拿到完整内容。源码通过两个类解决这个问题:

  • streaming_wrapper.py 中的 StreamingWrapper:基于 wrapt.ObjectProxy 包装原始流,在 __iter__ 迭代过程中把每个 PayloadPart 的 Bytes 解码后累积到 _accumulating_body,流耗尽后调用 stream_done 回调,由回调负责把累积的完整输出写入 span 属性并结束 span;
  • reusable_streaming_body.py 中的 ReusableStreamingBody:把底层 StreamingBody 的原始数据一次性读入内存缓冲区,从而允许同一个响应体被多次 read()——插桩先读一次写属性,你的业务代码随后还能再读一次拿到真实结果,互不干扰。

4.4 错误处理

插桩不会让可观测逻辑影响业务调用。当 invoke_endpoint 或 invoke_endpoint_with_response_stream 抛出异常时(如 AWS 的 ClientError),代码会:

  1. 在 span 上写入 error.type 属性(值为异常类名);
  2. 调用 record_exception 记录异常事件;
  3. 将 span 状态置为 StatusCode.ERROR 并携带错误信息;
  4. 重新抛出异常,保证业务侧原有行为不变。

这一行为在 test_error_handling.py 中有明确断言:异常后 span 状态为 ERROR、error.type 为 ClientError,且存在一条 exception 事件。

4.5 兜底保护:dont_throw

所有插桩内部处理逻辑(_handle_call、_handle_stream_call、流式事件解析等)都被 utils.py 中的 dont_throw 装饰器包裹:即便插桩自身解析失败,也只会记录 debug 日志(并可选调用 Config.exception_logger),绝不会把异常抛给用户代码。

五、隐私控制:TRACELOOP_TRACE_CONTENT

5.1 默认行为与风险

README 中明确强调:默认情况下,该插桩会把 SageMaker 端点的请求体与响应体完整记录到 span 属性中。这为调试和评估模型输出质量提供了极大便利,但请求/响应中可能包含用户的高度敏感数据,也会显著增大 trace 体积。

5.2 关闭内容记录

如需关闭,设置环境变量 TRACELOOP_TRACE_CONTENT 为 false:

TRACELOOP_TRACE_CONTENT=false

从 utils.py 的 should_send_prompts() 可以看到判定逻辑:

def should_send_prompts():
    return (
        os.getenv(TRACELOOP_TRACE_CONTENT) or "true"
    ).lower() == "true" or context_api.get_value("override_enable_content_tracing")

即:环境变量未设置时默认视为 "true"(记录内容);设为 "false" 时不再写入 traceloop.entity.input / traceloop.entity.output 等内容属性,但 gen_ai.request.model(端点名)这类元数据属性仍会保留。此外还支持通过 OpenTelemetry Context 键 override_enable_content_tracing 在运行时按请求粒度动态覆盖。

5.3 关闭后的具体效果

关闭内容记录后:

  • 同步调用:set_call_request_attributes / set_call_response_attributes 因 should_send_prompts() 为 False 而提前返回,不写入输入输出内容;
  • 流式调用:set_stream_response_attributes 同样跳过内容写入;
  • 事件路径(见下文第六节):事件中的 content 字段会被剔除(见 event_emitter.py 中 _emit_message_event / _emit_choice_event 对 body["content"] 的删除逻辑)。

六、两种输出模式:Span 属性 vs. 日志事件

从源码可以看到,该插桩在演进中支持两种内容承载方式,由 SageMakerInstrumentor 构造参数 use_attributes 控制(旧参数 use_legacy_attributes 已标记为弃用并会在未来版本移除):

  • use_attributes=True(默认,即 legacy 属性模式):prompt 与 completion 以 span 属性的形式写入,即上文提到的 traceloop.entity.input / traceloop.entity.output;
  • use_attributes=False(事件模式):prompt 与 completion 以 OpenTelemetry LogRecord 事件的形式发出,事件名为 gen_ai.user.message(输入)与 gen_ai.choice(输出),并携带 gen_ai.system: "sagemaker" 属性,对应事件模型见 event_models.py。

事件模式需要额外传入 logger_provider。测试 test_invocation.py 中覆盖了三条路径,正好可以作为两种模式的行为对照:

测试用例 模式 预期结果
test_sagemaker_completion_string_content_legacy use_legacy_attributes=True(默认) span 带 gen_ai.request.model 与 traceloop.entity.input,不产生日志事件
test_sagemaker_completion_string_content_with_events_with_content use_legacy_attributes=False + TRACELOOP_TRACE_CONTENT=True 产生 2 条事件:gen_ai.user.message 与 gen_ai.choice,且携带完整内容
test_sagemaker_completion_string_content_with_events_with_no_content use_legacy_attributes=False + TRACELOOP_TRACE_CONTENT=False 事件仍在,但内容字段为空

在事件模式下,emit_choice_events 会对响应列表逐条产出 gen_ai.choice 事件:同步响应取自 ReusableStreamingBody 的 generated_text 字段,流式响应则使用 StreamingWrapper 累积的完整文本。事件属性 EVENT_ATTRIBUTES = {gen_ai.system: "sagemaker"} 让这些事件可以与 span 正确关联并区分来源系统。

七、运行测试与本地验证

该包自带基于 VCR 录制的回放测试,无需真实 AWS 凭证即可验证插桩行为。测试数据位于 tests/cassettes/test_invocation/,其中记录了真实的 SageMaker 调用请求/响应(如 POST https://runtime.sagemaker.us-east-1.amazonaws.com/endpoints/my-llama2-endpoint/invocations)。

在包目录下运行:

uv run pytest tests/

测试通过 InMemorySpanExporter 与 InMemoryLogExporter 在进程内断言 span 属性和日志事件(见 conftest.py),同时用 mock 补丁模拟 ClientError 来验证错误路径(见 test_error_handling.py)。这是了解该插桩行为约定最直接的方式。

八、注意事项小结

  • 插桩只对 service_name="sagemaker-runtime" 生效,因此只观测 SageMaker 推理,不会干扰其他 AWS 服务调用;
  • TRACELOOP_TRACE_CONTENT=false 只影响内容属性,不影响 span 本身的生成与端点名等元数据;
  • use_legacy_attributes 已被弃用,新代码请使用 use_attributes;
  • 事件模式需要配置 OpenTelemetry LoggerProvider,否则事件不会被发出;
  • 若需深入了解语义约定的实现细节,可进一步阅读仓库内的 opentelemetry-semantic-conventions-ai 包,以及同类插桩(如 bedrock)对比其属性命名差异。

通过本文的安装、接入、隐私配置与源码原理,你已具备将 SageMaker 推理链路完整接入 OpenTelemetry 可观测体系的能力,可以在此基础上将 span 与事件接入 Trace 平台、告警规则与模型质量评估流程。

登录后查看全文
openllmetry