Skip to content

Telemetry集成

大模型Agent开发过程中，我们需要对Agent的运行状态进行监控，以便及时发现问题并进行调试。为了实现这一目标，我们使用了OpenTelemetry作为跟踪系统， 用于监控Agent的运行状态。OpenTelemetry是一个开源的跟踪系统，它提供了一套API和工具，用于收集、存储和可视化应用程序的跟踪数据。在大模型Agent中， 我们使用OpenTelemetry来监控Agent的运行状态，以便及时发现问题并进行调试。

而Telemetry模块主要是对OpenTelemetry进行一些扩展，以适应TFRobot的特殊需求： * TFRobot中，因为状态机的使用伴随着LLM具有驱动工具调用的能力，因此存在需要实时时监控当前信息流传递的需求，因为需要通过实时监控来及时发现是否有 无限循环（比如状态错位，或者大语言模型在无限调用工具）等情况出现。 而OpenTelemetry原生实现中，是在一个Span结束时，才会将Span的信息发送到后端， 这存在一种情况，嵌套的Span追踪，比如嵌套存在无限循环时， 会导致Span的监控输出无法推送到监控侧因此无法满足实时监控的需求。 * TFRobot利用Span的AddEvent能力做一些改造，添加了Hook能力，将在AddEvent时触发Hook函数，从而实现实时监控的能力。而在业务侧实现时，需要手动在需要监 控的关键节点触发AddEvent。为了简化实现，在各个基类进行了自动注入的处理，因此业务侧只需要在关键节点调用AddEvent即可。同时一些关键函数，目前也 已经通过装饰器实现了AddEvent的自动触发。

作为开发人员为项目添加新的通过OpenTelemetry实时监控的核心类，你应该遵循以下步骤和最佳实践。这个过程将包括设计和实现监控功能，以及与现有的 OpenTelemetry和TFRobot系统的集成。

  1. 步骤 1: 定义事件和上下文 首先，定义需要监控的事件类型。这些事件应该反映你想要监控的核心类的关键操作。 例如，在context_schema.py中定义的SpanEvent枚举类包含了不同的事件类型，如BEFORE_ROBOT_RUN和AFTER_ROBOT_RUN。

    • 选择和定义事件：基于你的核心类，选择或定义新的事件类型。

    • 创建上下文类：定义一个上下文类，包含与事件相关的详细信息。例如，RobotEventContext和BrainEventContext分别为Robot和Brain类提供了上下文。

    • 步骤 2: 实现Span装饰器 使用span_decorator函数来装饰你的核心类方法，这样就能在方法执行前后自动添加Span事件。

    • 定制装饰器：根据你的类方法定制装饰器参数，指定事件名称和生成上下文的函数。

    • 应用装饰器：将装饰器应用于核心类的方法。

    • 步骤 3: 钩子（Hook）的使用 实现一个或多个钩子（Hook），用于在事件发生时执行自定义逻辑。

    • 定义钩子：创建一个继承自BaseHook的类，实现execute方法。

    • 注册钩子：使用HookManager注册你的钩子，以便在特定事件发生时调用。

    • 步骤 4: 集成到Tracer 确保你的核心类能够通过TFTracer和TFSpan正确地集成OpenTelemetry跟踪。

    • 使用自定义Span：确保TFSpan的add_event方法能够处理你的事件。

    • 跟踪器设置：通过TFTracer和TFTracerProvider确保跟踪器正确配置。

    • 步骤 5: 测试和验证 进行彻底的测试以确保监控功能按预期工作。

    • 单元测试：编写针对新事件、上下文和钩子的单元测试。

    • 集成测试：确保当应用程序运行时，监控能够正确捕获和记录事件。

最佳实践

  • 代码清晰度：保持代码的清晰和可维护性，确保使用清晰的命名和充足的注释。
  • 模块化：保持代码的模块化，使不同的功能（如事件定义、上下文、钩子）保持独立。
  • 性能考虑：监控代码应该尽可能轻量，避免对应用程序性能产生负面影响。
  • 文档化：为新添加的监控功能提供详细的文档说明，以便其他开发人员理解和使用。

遵循这些步骤和最佳实践，你可以有效地为项目添加新的通过OpenTelemetry实时监控的核心类。