作者铖朴、瑜棕、顺岭背景随着 AI尤其是 Generative AI后文简称 GenAI的快速发展AI Agent 系统中涌现出大量新的核心概念例如 Model、Prompt、Token、Tool Calling、Agent、Memory、Session 等。这些概念已成为算法工程师、运维人员和可观测平台用户最关心的观测对象。它们需要像传统系统中的 HTTP 请求、数据库调用一样被标准化地采集、展示和消费以便系统维护者清晰了解调用过程、高效排查问题。基于此OpenTelemetry后文简称 OTel早在 2024 年初就开始推动 Gen AI 语义规范建设希望为这些新对象建立统一的数据采集规范——Semantic Conventions后文简称 SemConv以解决相关领域可观测数据采集标准缺失、口径不统一等问题。SemConv 定位与价值Java、Go 和 Python 等各语言的自动插桩Auto Instrumentation或 SDK 等可观测采集工具在许多对 OTel 刚接触的人眼里可能会认为它们是 OTel 社区的核心价值所在。然而深入了解社区后会发现相比于 SemConv这些采集能力更多扮演的是“术”的角色服务于 OTel 真正的“道”——通过 SemConv 建立统一的可观测数据语言。OTel SemConv 是一套汇聚全球几十家头部可观测厂商、数百名领域专家共同设计并持续演进的可观测数据采集标准。过去几年在多次 KubeCon 会议上与社区核心 Maintainer 和 Co-founder 交流后我们了解到在他们眼中SemConv 是 OTel 的灵魂推动其逐步完善并走向 Stable 是社区最重要的工作。一个统一的可观测 SemConv 可以实现如下效果统一数据语言解决口径不一致以 GenAI 语义为例其应用场景天然跨模型、跨框架、跨平台。没有统一语义规范时不同团队往往会各自记录“模型名”、“输入长度”、“Token 数”、“响应内容”等信息字段命名和统计口径无法对齐。OTel GenAI SemConv 的核心价值在于为这些通用概念提供标准化字段例如gen_ai.system、gen_ai.request.model、gen_ai.usage.input_tokens等。一旦这些关键字段被标准化不同业务、不同基础设施、不同观测后端就能共享同一套分析方法真正做到“同一类问题用同一套数据解释”。这也是语义规范最基础、最重要的价值。支撑性能、成本、质量与安全的统一治理可观测建设的目标不仅仅是排障还包括性能、效率、安全与输出行为的持续治理。比如在 GenAI SemConv 场景中统一的 SemConv 在把模型参数、响应元数据、Token 用量等关键信息标准化后团队才能更容易追踪性能、成本和安全相关问题。对大型企业来说这意味着可以在统一标准上解决如下几个实际诉求技术排查通过 Trace ID 查看跨 Agent 完整链路分钟级定位各类问题如某业务模型调用时延异常。经营分析效果数据跨业务可比直接用于产品决策极大提升 BI、产品、数科等角色做跨业务分析时的效率。评测真实用户轨迹持续积累自动构建评测数据集特别是多 Agent 协同场景的端到端评测。合规统一的审计链路满足安全备案刚性要求。如果没有统一语义这些问题就只能停留在单系统内局部分析无法形成集团级治理能力。降低接入成本推动基础设施复用OTel 的设计目标之一是通过标准协议、语义规范、SDK、自动插桩和 Collector 等组件让遥测数据可以复用同一条采集与治理链路。在 GenAI 场景中统一语义规范的价值也在这里体现得尤其明显一旦字段、Span 结构、事件模型和上下文传递方式定义清楚无侵入埋点、SDK 封装、平台分析、看板和告警策略都能复用。这意味着业务不需要每次都从“我要采什么字段”开始思考而可以直接站在已有规范之上接入能力降低整体建设成本。LoongSuite GenAI SemConv 介绍背景作为当前可观测业界的事实标准OTel 虽早在 2024 年初就开始了 GenAI 语义规范的讨论和设计但由于早期的人力投入有限再加上社区标准更强调广泛适用与长期稳定更新节奏整体较慢。相比之下阿里巴巴集团内部有大量的大模型应用落地场景遇到了大量真实场景中的案例问题因此有将相关问题抽象成为统一标准的诉求。2025 年阿里云、阿里控股与蚂蚁集团的可观测团队联合启动在 OTel GenAI 语义基础上对内部场景中 OTel 尚未覆盖的内容进行语义建模并基于此推进内部可观测采集工具的实现与落地。2026 年与 OTel 社区 GenAI 主要 Maintainer 沟通后考虑到相关内容较多且迭代较快在社区 Maintainer 的建议下先将成果开源至阿里巴巴 LoongSuite 可观测品牌下作为 OTel GenAI SemConv 的厂商增强标准后续择机逐步贡献至 OTel 上游。内容与落地目前该规范已在集团内多个核心场景完成落地形成了从 Agent 层到基建层的全栈可观测能力。例如以下是部分相关 Loongsuite GenAI SemConv[1]相比于 OTel GenAI SemConv[2]的增强内容新增 Entry/Step Span问题背景我们在 AI Agent 的实践过程中发现当 Agent 执行长程任务时其执行逻辑会变得越来越复杂。它会包含多轮工具调用和模型调用导致单个 Trace 中包含成百上千个 Span。这些 Span 在同一链路中展示时显得非常冗长导致调用链轨迹难以清晰观测。为了解决这个问题我们引入了以下两个关键设计1. Entry Span在 Agent 调用的入口处创建 Span用于还原模型和用户的原始输入、输出形成对话历史。这样可以确保在执行下游任务时处理的数据不受 System Prompt 或框架 Prompt 的干扰能够获取最原始的客户请求。2. Step SpanStep 代表 Agent 在每次 ReAct 过程中的层次化表达。在每次 ReAct 过程中Agent 都需要完成“反思 → 工具调用 → 模型调用”的循环。在排查问题时通常采用 Top-down 的方式来定位 Agent 的执行情况。具体流程是首先观察整体情况例如当 Agent 执行包含 10 轮 ReAct 过程时先定位是哪一轮出现问题然后再深入分析该轮中具体是哪一步出错。通过这种逐轮的 Span 结构可以清晰展示 Agent 的多轮行动、反思以及对应的执行结果使每轮循环的轨迹一目了然。语义建模新增的 Entry 和 Step Span 类型定义如下实现效果目前该语义规范已经在多个 Agent 场景中落地包括 OpenClawQwenPawHermes Agent以下是在 OpenClaw 场景下实现语义规范接入后的效果新增 Skill 语义问题背景在电商购物助手等 Agent 场景中用户的每条指令由 AI Agent 理解意图后路由到对应的Skill技能完成执行。Skill 是业务功能的最小可复用单元内部编排了一组 LLM 调用和工具调用用于完成特定任务例如搜索商品、加购物车、申请退款等。现有 OTel GenAI 语义约定已覆盖 Agent、LLM、Tool 等 Span 类型但缺少对 Skill 这一业务功能聚合层的抽象。Skill 既不是单一的 Tool 调用也不是完整的 Agent而是介于两者之间的编排单元。缺少 Skill 维度的可观测性意味着当性能抖动时我们只能看到一堆execute_tool和inference Span缺少 Skill 可观测性导致三个核心痛点无法归因到功能域性能抖动时只能看到一堆execute_tool和inference Span无法快速判断是哪个功能域出了问题。无法统计 Skill 健康指标缺少 Skill 粒度的 P99 延迟、成功率、调用频率等度量。多 Skill 并发时链路混淆不同 Skill 的 LLM/Tool Span 在 Trace 树中无法区分归属。语义建模为了实现对 Skill 信息的采集我们在 LoongSuite GenAI SemConv 中新增了一组gen_ai.skill.*属性用于标识 Skill 的身份与版本信息当前阶段这些属性附着在已有的execute_toolSpan 上无需引入新 Span 类型即可快速落地。同时基于集团业务我们落地了独立invoke_skillSpan 的方案并向 OTel 社区提交了提案 https://github.com/open-telemetry/semantic-conventions-genai/issues/86 以覆盖 Skill 从加载到执行完成的完整生命周期支撑按功能域的端到端分析。实现效果通过 Skill 语义属性可观测平台可以按功能域聚合分析快速定位“哪个 Skill 错误率最高”、对比“新版本 Skill 上线后延迟是否劣化”、度量“LLM 调用占 Skill 总耗时的比例”等。此外同一套gen_ai.skill语义约定也可覆盖各类框架如 OpenClaw、Langchain、Spring AI 等以下是 OpenClaw 场景下的埋点效果新增 Token 级推理观测问题背景2025 年上半年蚂蚁可观测团队围绕蚂蚁推理云服务建设了全链路可观测体系覆盖推理云服务核心组件构建了从客户端到引擎端的多语言、多协议分布式追踪 Trace 能力。其中蚂蚁与阿里云团队协作向社区三大推理引擎 vLLM、SGLang、TensorRT-LLM 贡献了基础的引擎可观测 Trace形成了蚂蚁和阿里集团层面事实上的可观测 Trace 标准。整个可观测体系是蚂蚁推理云服务重要的稳定性底盘。然而随着业务蓬勃发展推理云服务承压加剧推理引擎相关的疑难问题大量涌现请求级别的引擎 Trace 已无法有效定位更深层次的问题。我们深入研究推理引擎底层原理结合生产实际案例整理了如下问题1. 性能异常单个请求响应慢往往是因为某些 Token 生成慢而 Token 生成慢大概率是其他请求并发干扰导致的。2. 精度异常出现复读、答非所问、乱码等精度问题往往从某个 Token 开始异常后续 Token 受此影响持续出错。因此问题本质出在 Token 生成过程中。由此自然推演出推理请求问题定位定界必须以 Token 级别可观测数据作为支撑。因此2025 年下半年蚂蚁可观测团队率先构建了业界首个覆盖多推理引擎、支持 Token 级深度 Trace 的可观测产品把可观测性从宏观请求下沉到了微观 Token 维度。它不仅关注单个请求是否成功更深入观察每个 Token 的生成耗时及子阶段过程慢 Token 生成时同一推理实例内多请求并发的相互影响每个 Token 生成背后的 Top-K 候选分布帮助精度问题定位。这一工作的核心价值在于首次将推理引擎内部许多原本“黑盒”的过程拆解到 Token 粒度打造了一个可透视、可解释、可归因的白盒系统。语义建模推理引擎工作原理简介推理引擎本质上是一个无限循环执行迭代Iteration的系统。每个迭代根据资源情况和调度策略选取一批请求组成 Batch作为当前迭代的执行目标进行批量处理。迭代完成后被选中的每个请求通常会生成一个 Token。接着进入下一个迭代同样经历选取请求组成批-批量执行的过程。如此循环下去。Token 性能数据采集在每个请求的每个 Token 粒度我们采集进入迭代和退出迭代的时间戳。通过这两个时间戳可以推演出每个 Token 的调度时间、实际执行时间以及用户感知的总耗时。此外每个 Token 对应的请求都在一个 Batch 中Batch 的总请求数特别是总 Token 数刻画了批处理的负载该负载进一步决定了 Token 生成的耗时。因此我们定义了以下刻画 Token 粒度性能数据的相关属性Token 精度数据采集在每个请求的每个 Token 粒度我们采集每个 Token 对应的候选 Top-K Token 的概率分布。通过该分布可以判断模型输出质量质量差的模型其 Top 候选 Token 越不符合预期。如果模型输出符合预期但选中的 Token 不在 Top-K 中则问题指向用户指定的采样参数如温度等。所以我们定义了下面候选 Token 概率相关的属性实现效果基于上述设计的 GenAI 规范我们在三大引擎上进行采集并输出标准数据依托这份标准数据向用户展现出一致的功能界面。最终我们打造了引擎显微镜产品提供引擎并发与 Token 级别的推理引擎深度观测能力。引擎 Token 分析切换到高倍镜对准单个请求观察其内部 Token 生成的每一个步骤耗时以及 top 候选 Token 概率分布精准定位延迟根源与精度异常问题。引擎并发剖析使用广角镜头清晰呈现引擎所有请求的并发、竞争和协作关系快速识别资源冲突与瓶颈。引擎 Token 分析的 Token 粒度性能数据可以揭示有哪些慢 Token引擎并发分析进一步解答这些 Token 为什么慢另外 Token 粒度的概率分布数据可以揭示异常 Token 的大模型输出是否有正常还是采样参数设置不合理。产品上线后历经年底大促在稳定性战场成功帮助引擎/SRE/业务同学定位多起稳定性问题10 倍提速问题定界效率真正做到了又快又准并且进一步给出了优化建议。下面选择了一些比较典型的案例来阐述产品功能与业务价值。案例 1慢 Token 定位快速识别跨请求的资源干扰线上经常会碰到某个特定请求破线了比如指征 Token 输出速度的 TPOTToken 平均输出时间破线对用户来说会感受到输出的卡顿。下面这个案例讲述了这个场景下Token 分析与引擎并发剖析如何帮助定界定位。当我们拿到异常请求 TraceId 之后我们打开如下图所示的 Token 分析页面可以看到第 125 个 Token 花了 6.8 秒远超预期最终导致 TPOT 高达 54.77ms。点击 Token 分析右上角的“引擎并发分析”我们跳转到对应引擎实例并发剖析页面。根据时间或者 TraceId 搜索定位到异常请求。这个请求就是下图中的请求 2。我们看到请求 1 生成首 Tokenprefill 阶段-亮绿色块花了 6s中断了请求 2 去 decode 生成第 125 个 Token 黄色块跟 Token 分析吻合。总结下根因是其他租户的请求 prefill 中断了当前请求的 decode 过程那么可能的一个解决方案是去做 PD 分离避免不同请求的 prefill 和 decode 相互影响。案例 2Token 级观测精准定位答非所问的根因下面这个案例属于典型的“答非所问”案例比如用户问的是医疗问题但大模型回复了 LeetCode 解题答案。打开如下图异常 Trace 的 Token 分析页面我们一眼能看到首 Token 是“begin_of_sentence”。这个 Token 是一个特殊的 Token简称 BOS它被用来分割毫无关联的两个语料。也就是说一旦出现了 BOS那么接下来的回答就跟之前的 prompt 毫无关联自然而然就答非所问了。所以很明显在任何情况下回答里面都不应该出现 BOS那么问题定界到为何会出现这个 BOS。对于这个案例无论在用户的回复里面或者是引擎日志/网关日志里面都不会显示 “begin_of_sentence”而只会显示成空串所以没有 Token 分析定位过程会变得复杂。后续我们进一步挖掘发现产出 BOS 属于大模型的 badcase解决方案是调整模型或者等后续模型版本优化更新。使用 GenAI Utils 快速实现 LoongSuite GenAI SemConv背景在前文中我们详细介绍了 LoongSuite GenAI SemConv 在 Agent、Skill、Token Level Inference 等多个维度的语义建模。然而对于实现 LoongSuite GenAI SemConv 的各类插桩库Instrumentation开发者而言他们面临一个共同的工程挑战每个 GenAI 框架插桩库都需要实现一套完整的遥测采集逻辑——创建 Span、挂载语义属性、记录 Metrics、发送 Events、管理 Context 传递——而这些逻辑在不同框架插桩间高度重复。更关键的是当语义规范迭代升级时例如新增字段、调整 Span 结构若每个插桩库各自维护一套实现升级成本将成倍增长。以一个 Agent 框架插桩为例如果不使用公共工具层开发者需要手动完成创建 invoke_agent Span 并设置 SpanKind、逐一挂载 gen_ai.agent.name、gen_ai.agent.id、gen_ai.usage.input_tokens 等数十个属性、根据配置决定是否采集消息内容、处理异常并设置 Error 状态、记录 Duration 和 Token Usage Metrics——这些样板代码在每个插桩库中都大同小异。为了解决这一问题我们在探针中实现了 GenAI Utils它作为 LoongSuite GenAI SemConv 的工程化能力层将语义规范的复杂性封装成简洁的 API让插桩库开发者只需关注“从框架中提取什么数据”无需关心“如何按规范输出遥测数据”。以下是一些我们支持的 GenAI Utils 实现LoongSuite Python 对应实现 LoongSuite-utils-genai[3]。LoongSuite JS 对应实现 LoongSuite-utils-genai[4]。架构设计GenAI Utils 的整体架构遵循“分层解耦、统一收口”的设计原则核心设计理念插桩层只做数据提取各框架插桩库通过 Hook/Monkey-Patch 拦截框架调用将数据填充到对应的 Invocation 数据对象中不直接操作 OTel API。GenAI Utils 统一收口遥测输出所有 Span 创建、属性挂载、Metrics 记录、Event 发送、Context 管理均由 ExtendedTelemetryHandler 内部完成。规范升级只改一处当 LoongSuite GenAI SemConv 新增字段或调整结构时只需修改 GenAI Utils 中的 Span Utils 和 Metrics 模块所有下游插桩库自动生效。API 使用GenAI Utils 为 LoongSuite GenAI SemConv 覆盖的每种 GenAI 操作都提供了对应的 Invocation 数据类和 Context Manager 方法形成了统一的“填数据 交给 Handler”编程模型。接下来以 Python 语言 GenAI Utils 工具库为例介绍如何使用第一步获取 Handler 单例from opentelemetry.util.genai.extended_handler import get_extended_telemetry_handler handler get_extended_telemetry_handler( tracer_providertracer_provider, logger_providerlogger_provider, )ExtendedTelemetryHandler 继承自 OTel 上游的 TelemetryHandler负责基础 LLM 操作并在此基础上扩展了 Agent、Tool、Embedding、Retrieve、Rerank、Memory 等 LoongSuite 新增的操作类型同时还集成了多模态异步处理能力。这种继承设计确保了与上游社区代码同步时不产生冲突。第二步选择对应的 Invocation 数据类填充业务数据GenAI Utils 为每种操作定义了对应的 Invocation 数据类插桩库开发者只需将从框架中提取的数据填充其中第三步使用 Context Manager 完成遥测输出以典型的 Agent 框架插桩为例展示如何使用 GenAI Utils 快速实现完整的可观测采集from opentelemetry.util.genai.extended_handler import get_extended_telemetry_handler from opentelemetry.util.genai.extended_types import ( InvokeAgentInvocation, ExecuteToolInvocation ) from opentelemetry.util.genai.types import InputMessage, OutputMessage, Text handler get_extended_telemetry_handler() # Agent 调用 with handler.invoke_agent() as invocation: invocation.provider dashscope invocation.request_model qwen-max invocation.agent_name ShoppingAssistant invocation.agent_id agent-001 invocation.input_messages [ InputMessage(roleuser, parts[Text(content帮我推荐一款笔记本电脑)]) ] # ... 实际调用 Agent 框架 ... invocation.output_messages [ OutputMessage( roleassistant, parts[Text(content我来帮您搜索请稍等...)], finish_reasontool_calls ) ] invocation.input_tokens 42 invocation.output_tokens 18 # 工具执行 with handler.execute_tool() as invocation: invocation.tool_name search_products invocation.tool_call_arguments {query: 笔记本电脑, category: electronics} # ... 实际执行工具 ... invocation.tool_call_result {products: [{name: MacBook Pro, price: 12999}]}在上面这段代码中开发者没有直接操作任何 OTel API——不需要手动创建 Span、设置 SpanKind、挂载 gen_ai.agent.name 属性、记录 Duration Metrics——这些全部由 ExtendedTelemetryHandler 在 Context Manager 的enter和exit中自动完成。若在调用过程中抛出异常Handler 会自动捕获并在 Span 上设置 error.type 属性和错误状态。详细使用过程可以参考文档[5]。当前已支持的插桩基于 GenAI UtilsLoongSuite Python Agent 已实现以下 GenAI 框架和模型服务的插桩覆盖国内外主流 GenAI 生态这些插桩库的核心遥测逻辑全部复用 GenAI Utils 实现当 LoongSuite GenAI SemConv 新增语义或调整规范时只需要升级 opentelemetry-util-genai 包所有下游插桩库即可统一生效。结语从统一字段走向统一基础设施GenAI 时代的可观测建设已经从“为模型调用加日志埋点”演进到“为 Prompt、推理、检索、工具和 Agent 全链路建立统一语义”。OTel 已经为此提供了标准化方向并通过语义规范与插桩库推动 GenAI 观测能力的形成。阿里巴巴与蚂蚁集团共建 GenAI 可观测语义规范的意义正在于把这种标准化方向进一步工程化、平台化、规模化一方面用统一语义降低业务接入成本另一方面用统一数据驱动观测平台、分析服务和治理能力的复用。最终目标并不是“产出一份规范文档”而是让所有使用该套规范的厂商和用户能够为快速增长的 GenAI 应用真正做到可看见、可分析、可治理、可演进。社区本次 LoongSuite GenAI SemConv 发布只是一个开始未来我们会在以下几个方面持续努力更敏捷快速响应国内 AI 生态需求持续扩展插件矩阵更高效通过 LoongSuite GenAI Utils 提供更完善的多模态处理、更多 Span/Metric 类型、更新的语义规范端到端AI 调用与微服务调用统一追踪让多 Agent 全链路可观测成为可能与上游协同通过与上游 Maintainer 定期举行会议讨论规范与实现建设定期同步上游并将下游实践贡献回 OpenTelemetry 社区。如果你正在构建 AI 应用、关心可观测性欢迎试用、反馈与贡献LoongSuite GenAI SemConv 以及对应探针实现欢迎加以下钉钉群进行交流相关链接[1] Loongsuite GenAI SemConvhttps://github.com/alibaba/loongsuite-semantic-conventions-genai[2] OTel GenAI SemConvhttps://github.com/open-telemetry/semantic-conventions-genai[3] LoongSuite-utils-genaihttps://pypi.org/project/loongsuite-util-genai/[4] LoongSuite-utils-genaihttps://www.npmjs.com/package/loongsuite/opentelemetry-util-genai[5] 文档https://github.com/alibaba/loongsuite-python-agent/blob/main/util/opentelemetry-util-genai/README-loongsuite.rst