ADK 的 Monocle 可观测性¶

Supported in ADKPython

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 的可观测性后端兼容。