使用 Monocle 进行智能体可观测性¶

Monocle 是一个开源的可观测性平台，用于监控、调试和改进 LLM 应用程序和 AI 智能体。它通过自动插桩为你的 Google ADK 应用程序提供全面的追踪能力。Monocle 生成与 OpenTelemetry 兼容的追踪数据，可以导出到各种目标，包括本地文件或控制台输出。

概述¶

Monocle 自动为 Google ADK 应用程序插桩，让你能够：

追踪智能体交互 - 自动捕获每次智能体运行、工具调用和模型请求，包含完整的上下文和元数据
监控执行流程 - 通过详细的追踪跟踪智能体状态、委托事件和执行流程
调试问题 - 分析详细的追踪数据以快速识别瓶颈、失败的工具调用和意外的智能体行为
灵活的导出选项 - 将追踪数据导出到本地文件或控制台进行分析
OpenTelemetry 兼容 - 生成标准的 OpenTelemetry 追踪数据，可与任何兼容 OTLP 的后端配合使用

Monocle 自动为以下 Google ADK 组件插桩：

BaseAgent.run_async - 捕获智能体执行、智能体状态和委托事件
FunctionTool.run_async - 捕获工具执行，包括工具名称、参数和结果
Runner.run_async - 捕获运行器执行，包括请求上下文和执行流程

安装¶

1. 安装所需包¶

pip install monocle_apptrace google-adk

设置¶

1. 配置 Monocle 遥测¶

当你初始化遥测时，Monocle 会自动为 Google ADK 插桩。只需在应用程序开始时调用 setup_monocle_telemetry():

from monocle_apptrace import setup_monocle_telemetry

# 初始化 Monocle 遥测 - 自动为 Google ADK 插桩
setup_monocle_telemetry(workflow_name="my-adk-app")

就是这样!Monocle 将自动检测并为你的 Google ADK 智能体、工具和运行器插桩。

2. 配置导出器 (可选)¶

默认情况下，Monocle 将追踪数据导出到本地 JSON 文件。你可以使用环境变量配置不同的导出器。

导出到控制台 (用于调试)¶

设置环境变量：

export MONOCLE_EXPORTER="console"

导出到本地文件 (默认)¶

export MONOCLE_EXPORTER="file"

或者简单地省略 MONOCLE_EXPORTER 变量 - 它默认为 file。

观测¶

现在你已经设置了追踪，所有 Google ADK SDK 请求都将被 Monocle 自动追踪。

from monocle_apptrace import setup_monocle_telemetry
from google.adk.agents import Agent
from google.adk.runners import InMemoryRunner
from google.genai import types

# 初始化 Monocle 遥测 - 必须在使用 ADK 之前调用
setup_monocle_telemetry(workflow_name="weather_app")

# 定义一个工具函数
def get_weather(city: str) -> dict:
    """检索指定城市的当前天气报告。

    Args:
        city (str): 要检索天气报告的城市名称。

    Returns:
        dict: 状态和结果或错误消息。
    """
    if city.lower() == "new york":
        return {
            "status": "success",
            "report": (
                "纽约的天气晴朗，温度为 25 摄氏度"
                "(77 华氏度)。"
            ),
         }
    else:
        return {
            "status": "error",
            "error_message": f"'{city}' 的天气信息不可用。",
         }

# 创建一个带工具的智能体
agent = Agent(
    name="weather_agent",
    model="gemini-2.0-flash-exp",
    description="使用天气工具回答问题的智能体。",
    instruction="你必须使用可用的工具来找到答案。",
    tools=[get_weather]
)

app_name = "weather_app"
user_id = "test_user"
session_id = "test_session"
runner = InMemoryRunner(agent=agent, app_name=app_name)
session_service = runner.session_service

await session_service.create_session(
    app_name=app_name,
    user_id=user_id,
    session_id=session_id
)

# 运行智能体 (所有交互都将被自动追踪)
async for event in runner.run_async(
    user_id=user_id,
    session_id=session_id,
    new_message=types.Content(role="user", parts=[
        types.Part(text="纽约的天气怎么样？")]
    )
):
    if event.is_final_response():
        print(event.content.parts[0].text.strip())

访问追踪数据¶

默认情况下，Monocle 在本地目录 ./monocle 中生成 JSON 格式的追踪文件。文件名格式为：

monocle_trace_{workflow_name}_{trace_id}_{timestamp}.json

每个追踪文件包含一个 OpenTelemetry 兼容的 span 数组，捕获：

智能体执行 span - 智能体状态、委托事件和执行流程
工具执行 span - 工具名称、输入参数和输出结果
LLM 交互 span - 模型调用、提示、响应和 token 使用情况 (如果使用 Gemini 或其他 LLM)

你可以使用任何兼容 OpenTelemetry 的工具分析这些追踪文件，或编写自定义分析脚本。

使用 VS Code 扩展可视化追踪数据¶

Okahu Trace Visualizer VS Code 扩展提供了一种交互式方式，可以直接在 Visual Studio Code 中可视化和分析 Monocle 生成的追踪数据。

安装¶

打开 VS Code
按 Ctrl+P(或 Mac 上的 Cmd+P) 打开快速打开
粘贴以下命令并按 Enter:

ext install OkahuAI.okahu-ai-observability

或者，你可以从 VS Code Marketplace 安装它。

功能¶

该扩展提供：

自定义活动栏面板 - 用于追踪文件管理的专用侧边栏
交互式文件树 - 使用自定义 React UI 浏览和选择追踪文件
分屏视图分析 - 甘特图可视化与 JSON 数据查看器并排显示
实时通信 - VS Code 和 React 组件之间的无缝数据流
VS Code 主题 - 完全集成 VS Code 的亮色/暗色主题

使用¶

在启用 Monocle 追踪的情况下运行 ADK 应用程序后，追踪文件将在 ./monocle 目录中生成
从 VS Code 活动栏打开 Okahu Trace Visualizer 面板
从交互式文件树中浏览并选择追踪文件
查看你的追踪数据：
甘特图可视化 - 查看 span 的时间线和层次结构
JSON 数据查看器 - 检查详细的 span 属性和事件
Token 计数 - 查看 LLM 调用的 token 使用情况
错误徽章 - 快速识别失败的操作

Monocle VS Code Extension

追踪的内容¶

Monocle 自动从 Google ADK 捕获以下信息：

智能体执行: 智能体状态、委托事件和执行流程
工具调用: 工具名称、输入参数和输出结果
运行器执行: 请求上下文和整体执行流程
时间信息: 每个操作的开始时间、结束时间和持续时间
错误信息: 异常和错误状态

所有追踪数据都以 OpenTelemetry 格式生成，使其与任何兼容 OTLP 的可观测性后端兼容。