Telemetry 遥测系统

TFRobot 的遥测系统解决一个核心问题：在 Agent 运行过程中实时观测其内部状态。

大语言模型 Agent 的执行链路深且不确定——状态机驱动推理、LLM 多轮调用、工具执行、记忆检索层层嵌套。如果只在整条链路结束后才输出追踪数据（这是 OpenTelemetry 的默认行为），那么当 Agent 陷入无限循环或工具调用失控时，外部完全无法感知。

TFRobot 对 OpenTelemetry 做了针对性扩展，使得每个关键节点在执行的瞬间就能向外发出事件，而不必等待整条链路结束。

架构总览

graph TB
    subgraph TFRobot 组件
        Robot --> Brain --> Chain
        Chain --> LLM
        Chain --> Tool
        Chain --> Memory
    end

    subgraph Telemetry 扩展层
        SD["span_decorator<br/>自动包装关键方法"]
        TFS["TFSpan<br/>覆写 add_event"]
        HM["HookManager<br/>事件分发（单例）"]
    end

    subgraph 用户侧
        H1["Hook A<br/>日志打印"]
        H2["Hook B<br/>指标上报"]
        H3["Hook C<br/>业务回调"]
    end

    Chain -.->|方法被包装| SD
    LLM -.->|方法被包装| SD
    Tool -.->|方法被包装| SD
    Memory -.->|方法被包装| SD
    SD -->|构造 EventContext| TFS
    TFS -->|add_event 触发| HM
    HM --> H1
    HM --> H2
    HM --> H3

数据流时序

以一次 Chain 调用 LLM 为例，事件的产生与消费过程如下：

sequenceDiagram
    participant User as 调用方
    participant Chain
    participant LLM
    participant SD as span_decorator
    participant HM as HookManager
    participant Hook as 用户 Hook

    User->>Chain: run()
    activate Chain
    SD->>HM: before_chain_run + ChainEventContext
    HM->>Hook: execute(event, context)

    Chain->>LLM: complete()
    activate LLM
    SD->>HM: before_llm_generate + LLMEventContext
    HM->>Hook: execute(event, context)
    LLM-->>Chain: result
    SD->>HM: after_llm_generate + LLMEventContext（含 token_usage）
    HM->>Hook: execute(event, context)
    deactivate LLM

    Chain-->>User: result
    SD->>HM: after_chain_run + ChainEventContext
    HM->>Hook: execute(event, context)
    deactivate Chain

核心扩展点

TFRobot 对 OpenTelemetry 的扩展集中在三个类上：

扩展类	原生类	改造点
TFTracerProvider	TracerProvider	返回 TFTracer 而非原生 Tracer
TFTracer	Tracer	创建 TFSpan 而非原生 Span
TFSpan	Span	add_event 时同步触发 HookManager

原生 OpenTelemetry 在 Span 结束时才导出数据。TFSpan 在 add_event 的调用瞬间就通过 HookManager 分发事件，实现实时可观测。

详细实现参见 Trace 扩展。

模块导航

文档	内容
Trace 扩展	TFTracerProvider / TFTracer / TFSpan 的实现细节与使用方式
场景与事件	Scene（事件来源）和 SpanEvent（事件类型）的完整定义
Event Hook	如何编写 Hook 监听事件，EventContext 各场景字段参考
透传原始上下文	通过 OpenTelemetry Baggage 将业务上下文透传到 Hook
Meter 指标采集	指标体系设计、LLM Token 采集实现、MeterProvider 策略
扩展事件	如何为新组件添加自定义 Scene 和 Event