Skip to content

用于 ADK 的 Google Cloud Trace 可观测性

Supported in ADKPythonTypeScriptGo

在本地开发期间，你可以使用 ADK Web UI 中的 Trace 视图 来检查智能体行为。一旦你的智能体部署完成，你需要一种方式在一个地方观察来自真实流量的追踪数据。

Cloud Trace 是 Google Cloud 可观测性的分布式追踪组件。它收集并可视化追踪数据，使你能够监控延迟、调试错误并提升应用程序的整体性能。对于 ADK 智能体，Cloud Trace 捕获每个请求如何流经模型调用、工具执行和智能体步骤，从而使你能够在生产环境中精确定位瓶颈和错误。

Cloud Trace 构建在 OpenTelemetry 之上，这是一个开源标准，支持多种语言和摄取方法来生成追踪数据。这与 ADK 应用程序的可观测性实践一致，ADK 也利用了兼容 OpenTelemetry 的仪表化功能，从而允许你：

  • 追踪智能体交互：Cloud Trace 持续收集和分析项目中的追踪数据，使你能够快速诊断 ADK 应用中的延迟问题和错误。这种自动化的数据收集简化了在复杂智能体工作流中识别问题的过程。
  • 调试问题：通过分析详细的追踪数据，快速诊断延迟问题和错误。这些追踪对于理解表现为跨不同服务通信延迟增加的问题，或在特定智能体操作（如工具调用）期间出现的问题至关重要。
  • 深入分析和可视化：Trace Explorer 是分析追踪的主要工具，提供可视化辅助功能，如 span 持续时间的热力图和 span 速率的折线图。它还提供了可按服务和操作分组的 spans 表格，可一键访问代表性追踪和瀑布图视图，便于在智能体执行路径中识别瓶颈和错误来源。
working_dir/
├── weather_agent/
│   ├── agent.py
│   └── __init__.py
└── deploy_agent_engine.py
└── deploy_fast_api_app.py
└── agent_runner.py

# weather_agent/agent.py

import os
from google.adk.agents import Agent

os.environ.setdefault("GOOGLE_CLOUD_PROJECT", "{你的项目ID}")
os.environ.setdefault("GOOGLE_CLOUD_LOCATION", "global")
os.environ.setdefault("GOOGLE_GENAI_USE_ENTERPRISE", "True")

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

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

    返回：
        dict: 状态和结果或错误消息。
    """
    if city.lower() == "new york":
        return {
            "status": "success",
            "report": (
                "纽约的天气是晴天，温度为 25 摄氏度"
                " (77 华氏度)。"
            ),
        }
    else:
        return {
            "status": "error",
            "error_message": f"无法获取 '{city}' 的天气信息。",
        }

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

Cloud Trace 设置

使用 ADK CLI

你可以通过在使用 ADK CLI 部署或运行智能体时添加标志来启用云端追踪。

使用 adk deploy 命令部署智能体时：

adk deploy agent_engine \
    --project=$GOOGLE_CLOUD_PROJECT \
    --region=$GOOGLE_CLOUD_LOCATION \
    --trace_to_cloud \
    $AGENT_PATH

使用 ADK Go 启动器运行智能体时：

adkgo web -otel_to_cloud

编程方式设置

使用 ADK 应用抽象

如果你正在使用 AdkApp 抽象，可以通过添加 enable_tracing=True 来启用云端追踪：

from google.adk.apps import AdkApp

adk_app = AdkApp(
    agent=root_agent,
    enable_tracing=True,
)

使用遥测模块

对于完全定制的智能体运行时，你可以使用内置的遥测模块启用云端追踪。

from google.adk import telemetry
from google.adk.telemetry import google_cloud

# 获取 GCP 导出器配置
hooks = google_cloud.get_gcp_exporters(enable_cloud_tracing=True)

# 初始化并设置全局 OTel 提供程序
telemetry.maybe_set_otel_providers(otel_hooks_to_setup=[hooks])

import { getGcpExporters, maybeSetOtelProviders } from '@google/adk';

// 获取 GCP 导出器配置
const gcpExporters = await getGcpExporters({
  enableTracing: true,
});

// 初始化并设置全局 OTel 提供程序
maybeSetOtelProviders([gcpExporters]);

// ... 你的智能体代码 ...

import (
    "context"
    "log"
    "time"

    "google.golang.org/adk/v2/telemetry"
)

func main() {
    ctx := context.Background()

    // 初始化遥测并启用云端导出。
    // 默认情况下，从 GOOGLE_CLOUD_PROJECT 环境变量读取 GCP 项目 ID。
    // 你也可以使用 telemetry.WithGcpResourceProject("my-project") 显式指定。
    telemetryProviders, err := telemetry.New(ctx,
        telemetry.WithOtelToCloud(true),
        // telemetry.WithGcpResourceProject("your-project-id"),
    )
    if err != nil {
        log.Fatalf("无法初始化遥测: %v", err)
    }
    defer func() {
        shutdownCtx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
        defer cancel()
        if err := telemetryProviders.Shutdown(shutdownCtx); err != nil {
            log.Printf("无法关闭遥测: %v", err)
        }
    }()

    // 注册为全局 OTel 提供程序
    telemetryProviders.SetGlobalOtelProviders()

    // ... 你的智能体代码 ...
}

查看 Cloud Trace 数据

设置完成后，每当你与智能体交互时，它都会自动将追踪数据发送到 Cloud Trace。你可以通过访问 Google Cloud 控制台 中的 Trace Explorer 来查看追踪数据。

cloud-trace

你将看到 ADK 智能体产生的所有可用追踪，其 span 名称包括 invoke_agent、generate_content、call_llm 和 execute_tool。

cloud-trace

如果你点击其中一条追踪，你将看到详细过程的瀑布图视图，类似于本地 ADK Web UI 中的追踪视图。

cloud-trace

捕获的属性

ADK 会自动使用以下属性丰富追踪数据，帮助你筛选和分析智能体的行为：

  • gen_ai.agent.name：正在执行的智能体的名称。
  • gcp.vertex.agent.invocation_id：调用的唯一 ID。
  • gcp.vertex.agent.event_id：特定事件的 ID。
  • gen_ai.conversation.id：会话 ID。

资源

要了解更多关于追踪、OpenTelemetry 和 Google Cloud 集成的信息，请查阅以下文档：