OpenTelemetry AI 怎样把模型调用耗时纳入 trace

我第一次给模型请求接入 OpenTelemetry 时，业务接口已经有 trace，慢请求却只能看到一段笼统的 HTTP 耗时，无法回答“究竟是排队、网络还是模型生成变慢”。解决办法不是手工写一个 duration 属性，而是在真正的模型客户端调用外包一层 GenAI client span：从发起请求开始，到完整响应、流式最后一个 chunk、错误或取消结束。trace 会根据 span 的开始和结束时间计算这次调用的持续时间。

官方地址：https://opentelemetry.io/docs/

把模型调用耗时纳入 trace 的关键，是让 span 边界准确包住模型请求；需要查看 P50、P95 等整体分布时，再用 histogram 记录同一边界的秒数。单次 trace 负责定位，指标负责聚合，两者不要混成一个高基数属性表。

先看症状：接口有耗时，模型却没有自己的子 span

常见现场是这样的：入口 HTTP span 持续了 4 秒，内部业务函数也在 trace 中，但模型 SDK 调用没有独立子 span。此时只能知道“请求很慢”，却不能区分模型等待、响应读取和业务后处理。根因通常不是 exporter 丢了一个字段，而是埋点只包住了业务函数，或者 span 在发出请求后就提前结束了。

排查时先确认三件事：模型调用是否发生在当前 trace 上下文内；span 是否覆盖了真正的 provider 请求；流式响应是否在消费完最后一个 chunk 后才结束。如果只在创建请求对象时结束 span，看到的只是本地准备时间，不是模型调用耗时。

把 span 边界放在模型请求两侧

OpenTelemetry Python 的手动 instrumentation 可以用 start_as_current_span 创建当前 span。下面的 provider_call 只是替换点，实际项目中应换成自己的模型 SDK；示例展示的是边界和属性，不绑定某个厂商。

from time import monotonic

from opentelemetry import metrics, trace
from opentelemetry.trace import SpanKind, Status, StatusCode

tracer = trace.get_tracer("app.ai")
meter = metrics.get_meter("app.ai")
# 记录与 span 同一边界的端到端秒数，便于后续统计分布。
model_duration = meter.create_histogram(
    "gen_ai.client.inference.duration",
    unit="s",
    description="模型客户端推理调用的端到端时长",
)


def call_model(messages, model_name):
    # 只放低基数、非敏感属性，便于采样和聚合。
    attributes = {
        "gen_ai.operation.name": "chat",
        "gen_ai.provider.name": "example-provider",
        "gen_ai.request.model": model_name,
    }
    started = monotonic()
    with tracer.start_as_current_span(
        f"chat {model_name}",
        kind=SpanKind.CLIENT,
        attributes=attributes,
    ) as span:
        try:
            # 这里必须等待完整响应；流式调用要在消费完最后一个 chunk 后离开 with。
            response = provider_call(messages, model=model_name)
            span.set_attribute(
                "gen_ai.response.model",
                getattr(response, "model", model_name),
            )
            return response
        except Exception as exc:
            # 失败调用也要保留在 trace 中，便于区分超时、取消和服务端错误。
            span.record_exception(exc)
            span.set_status(Status(StatusCode.ERROR, "模型请求失败"))
            span.set_attribute("error.type", type(exc).__name__)
            raise
        finally:
            # 指标与 span 使用同一端点，单次 trace 和聚合结果才可对照。
            model_duration.record(monotonic() - started, attributes)

这里真正重要的是 with 的范围：模型请求之前进入，完整响应之后离开。非流式调用通常自然满足这一点；流式调用则要把“迭代响应”的代码放进 span 内部，否则记录到的可能只是建立连接或拿到迭代器的时间。

trace 时长和聚合指标要分工

单条 trace 已经有 span 的起止时间，可以直接查看一次调用耗时、父子关系和异常位置；不必为了展示耗时再给 span 加一个手工 duration_ms 属性。这个属性既可能和真实 span 时长不一致，也会让事件模型变得重复。

如果要回答“这个模型最近的 P95 是多少”，就需要 histogram。GenAI 语义约定把模型推理时长定义为从客户端发起请求到完整响应或错误、取消结束的端到端时间；当前相关规范仍处于 Development，具体 instrumentation 可能使用 gen_ai.client.inference.duration 或演进中的其他细分名称，接入时应以所采用版本的官方定义为准。

属性建议从低基数开始：gen_ai.operation.name 表示 chat 等操作，gen_ai.provider.name 表示服务提供方，gen_ai.request.model 表示请求模型，失败时补充 error.type。不要把完整 prompt、回答、用户 ID 或动态请求内容直接作为常规 span 属性；这些内容可能包含敏感信息，也会迅速放大存储和查询成本。

复查时重点看四个容易漏掉的边界

我实际会把“trace 中的一次 span”和“指标中的一条 histogram 观测”当成同一个边界的两种视图：前者用于定位某一次慢调用，后者用于发现整体趋势。这样遇到超时、取消或模型切换时，既能回到具体请求，又不会把所有 prompt 内容塞进可观测性系统。

常见问题

只记录 HTTP client span，能代表模型耗时吗？

只能近似表示一次网络请求。它可能缺少模型语义属性，也不能清楚区分模型客户端内部排队、响应解码和业务后处理。更稳妥的做法是在模型调用边界补一个 GenAI span，并避免重复包住同一段 HTTP 调用。

模型返回流式内容时，span 什么时候结束？

应在消费完最后一个 chunk 后结束；如果流被取消或中途抛错，也要在异常路径结束并记录错误。只包住“发起流式请求”的代码，会把生成阶段漏掉。

必须把 prompt 和回答写进 trace 吗？

不必须。模型输入输出可能含有个人信息、业务机密或大段文本，优先记录模型、provider、操作、错误类型和 token 统计等必要字段；内容采集应采用明确的 opt-in 策略，并配合截断、脱敏和访问控制。

总结

OpenTelemetry AI 纳入模型调用耗时可以记成三句话：在真实模型请求两侧创建 GenAI client span，让 span 覆盖完整响应或错误取消；用稳定的 gen_ai.* 属性描述调用，不把 prompt 当成普通标签；需要 P50/P95 时，再用与同一边界对应的 duration histogram 聚合。trace 解决“这一单为什么慢”，指标解决“最近整体是不是变慢”。

参考资料

OpenTelemetry Python instrumentation：https://opentelemetry.io/docs/languages/python/instrumentation/

GenAI client inference 语义约定：https://github.com/open-telemetry/semantic-conventions-genai/blob/main/docs/gen-ai/client-inference.md

GenAI metrics 定义：https://github.com/open-telemetry/semantic-conventions-genai/blob/main/model/gen-ai/metrics.yaml