用 OpenTelemetry 追踪 Amazon SageMaker 推理调用:openllmetry SageMaker 插桩实践指南
用 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),代码会:
- 在 span 上写入
error.type属性(值为异常类名); - 调用
record_exception记录异常事件; - 将 span 状态置为
StatusCode.ERROR并携带错误信息; - 重新抛出异常,保证业务侧原有行为不变。
这一行为在 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 平台、告警规则与模型质量评估流程。