企业级 AI Agent 全链路可观测性实战：OpenTelemetry 扩展、多步推理追踪与 Token 消耗归因

【企业级 AI Agent 分层 Span 拓扑规范】

• 1. 根跨度（Root Span - agent.workflow）：
  代表终端用户发起的一次完整业务交互会话。必须附带 tenant.id（租户编号）、user.id（操作员编号）、session.id（会话ID）及 workflow.name（业务工作流名称）。记录整体响应延迟与最终业务完成状态。
• 2. 步骤跨度（Step Span - agent.step）：
  在多轮 ReAct 或 Plan-and-Solve 执行中，每个独立的决策循环封装为一个 Step Span。属性包含 step.index（步骤序号）、step.type（planning / tool_execution / synthesis）以及是否触发了熔断防御。
• 3. 检索跨度（Retrieval Span - gen_ai.retrieval）：
  涵盖知识库向量化查询、混合检索与重排序全过程。必须记录 db.system（如 milvus/qdrant）、retrieval.query（改写后查询词）、retrieval.top_k、以及召回切片的最高分值与重排耗时。
• 4. 模型推理跨度（LLM Span - gen_ai.client）：
  直连私有化推理网关（vLLM / TGI）或商业模型 API。标准化记录 gen_ai.system、gen_ai.request.model、gen_ai.usage.input_tokens、gen_ai.usage.output_tokens 以及首字到达时间（TTFT, Time-to-First-Token）。
• 5. 工具调用跨度（Tool Span - agent.tool_call）：
  下发给业务系统（ERP、OA、MES）的动作。记录 tool.name、tool.parameters（脱敏后）、tool.execution_status 与业务接口返回耗时。

# 文件位置：bxagent/observability/tracer.py
from opentelemetry import trace
from opentelemetry.trace import Status, StatusCode
import time

tracer = trace.get_tracer("bxagent.core.workflow", "1.0.0")

class AgentTraceContext:
    # 执行大模型推理并自动注入标准化 GenAI 属性
    @staticmethod
    async def trace_llm_inference(model_name: str, prompt_tokens: int, call_fn):
        with tracer.start_as_current_span("gen_ai.client.generate") as span:
            span.set_attribute("gen_ai.system", "vllm")
            span.set_attribute("gen_ai.request.model", model_name)
            span.set_attribute("gen_ai.usage.input_tokens", prompt_tokens)

            start_time = time.perf_counter()
            try:
                result = await call_fn()
                # 记录模型生成的补全 Token 数量与首字时延
                span.set_attribute("gen_ai.usage.output_tokens", result.output_tokens)
                span.set_attribute("gen_ai.response.finish_reason", result.finish_reason)
                span.set_status(Status(StatusCode.OK))
                return result
            except Exception as e:
                # 捕获推理异常，如显存溢出（OOM）或上下文超长截断
                span.record_exception(e)
                span.set_status(Status(StatusCode.ERROR, str(e)))
                raise e

【企业级可观测性安全与采样三大黄金法则】

• 1. 内存级探针前置动态脱敏（In-Memory Masking）：
  在将 Prompt 或工具调用参数写入 Span 属性之前，由内置安全拦截器基于预置正则表达式（如手机号、银行卡、身份证）与语义命名实体识别（NER）执行掩码处理（如 138****0000），确保脱敏操作在内存中即刻完成，绝不向存储层泄漏明文。
• 2. 区分审计通道与诊断通道（Audit vs Tracing Separation）：
  将合规审计日志与工程性能追踪物理分离。合规审计日志采用国密加密存储于只读合规库，而 APM 追踪链路仅保留脱敏后的语义指纹、Token 指标与耗时，防止运维工程师通过 APM 界面越权窥探业务机密。
• 3. 尾部自适应采样（Tail-Based Adaptive Sampling）：
  针对正常、高频且耗时低于 1.5 秒的简单会话，按 5%~10% 的低比例进行随机采样以节约存储开销；而对于耗时超过 3 秒的慢调用、HTTP 状态码异常、触发模型重试或参数校验失败的异常会话，实施 100% 全量保留，确保每一个故障现场都拥有完整的追溯数据。