TFRobot 指标体系设计 / TFRobot Metrics System Design¶
1. OpenTelemetry 集成概述 / OpenTelemetry Integration Overview¶
TFRobot 全面采用 OpenTelemetry 作为分布式追踪与指标采集框架，实现对核心业务链路的可观测性。
TFRobot uses OpenTelemetry for distributed tracing and metrics collection, providing observability for core business flows.
2. TraceProvider 个性化扩展 / TraceProvider Customization¶
2.1 扩展背景 / Extension Background¶
TFRobot 需要对业务流程中的关键事件进行实时、个性化的事件采集，因此对 OpenTelemetry 的 TraceProvider、Tracer、Span 进行了扩展，增强了 Event 的钩子能力。
TFRobot extends OpenTelemetry's TraceProvider, Tracer, and Span to support real-time, customizable event collection via event hooks.
2.2 实现方式 / Implementation¶
- 自定义
TFTracerProvider、TFTracer和TFSpan，在TFSpan.add_event时自动触发钩子（Hook），实现事件的实时处理与扩展。 - 事件上下文通过 Pydantic Schema 结构化，便于后续数据分析与分类。
-
业务层只需在关键节点调用
add_event，无需关心底层实现。 -
Custom
TFTracerProvider,TFTracer, andTFSpantrigger hooks automatically inTFSpan.add_event, enabling real-time event processing. - Event context is structured via Pydantic schemas for easy analysis and classification.
- Business code only needs to call
add_eventat key points, without caring about the underlying details.
3. MeterProvider 设计 / MeterProvider Design¶
TFRobot 不在内部定义 MeterProvider，而是直接使用 OpenTelemetry 默认实现，由外部调用者（如 TFRobotServer、Celery 等）进行设置和接管。
TFRobot does not define a custom MeterProvider internally, but uses OpenTelemetry's default implementation, allowing external callers to configure and manage it.
4. 指标体系设计 / Metrics System Design¶
4.1 设计原则 / Design Principles¶
- 关注 LLM 资源消耗、工具调用、流程异常等核心环节
- 指标类型选择遵循 OpenTelemetry 标准（Counter、UpDownCounter、Histogram 等）
-
结构化标签，便于多维度分析
-
Focus on LLM resource consumption, tool invocation, and process exceptions
- Metric types follow OpenTelemetry standards (Counter, UpDownCounter, Histogram, etc.)
- Structured labels for multi-dimensional analysis
4.2 指标明细 / Metric Details¶
4.2.1 LLM Token 消耗 / LLM Token Consumption¶
- 指标名称 / Name：
llm.tokens.total、llm.tokens.prompt、llm.tokens.completion - 类型 / Type：
Counter - 标签 / Labels：
model_name,user_id,scene,chain_id等 - 说明 / Description：分别统计 LLM 总 Token、Prompt Token、Completion Token 的消耗量
- 采集方式 / Collection：在每次 LLM 调用后，自动上报各类 Token 消耗
4.2.2 工具调用次数 / Tool Invocation Count¶
- 指标名称 / Name：
tool.invocation.count - 类型 / Type：
Counter - 标签 / Labels：
tool_name,user_id,scene,chain_id等 - 说明 / Description：统计各类工具被调用的次数
- 采集方式 / Collection：每次工具调用时自动递增计数
4.2.3 Chain 失败次数与原因 / Chain Failure Count & Reason¶
- 指标名称 / Name：
chain.failure.count - 类型 / Type：
Counter - 标签 / Labels：
failure_reason,user_id,scene,chain_id等 - 说明 / Description：统计 Chain 执行失败的次数，并对失败原因进行分类
- 采集方式 / Collection：在 Chain 执行异常时自动上报，并标注详细原因
5. 总结 / Summary¶
TFRobot 的指标体系以 OpenTelemetry 为核心，结合自定义 TraceProvider 实现灵活、实时的事件与指标采集。各项指标均采用标准化类型与结构化标签，便于后续监控、告警和数据分析。
TFRobot's metrics system leverages OpenTelemetry and custom TraceProvider for flexible, real-time event and metric collection. All metrics use standardized types and structured labels for monitoring, alerting, and analytics.