智能体活动指标¶

Supported in ADKPython v1.32.0

Agent Development Kit (ADK) 提供内置的、供应商中立的指标收集功能，帮助你了解智能体的性能、成本和使用模式。日志提供了发生了什么的详细叙述，而指标则提供了聚合的定量数据，用于回答事情发生的频率和速度。

指标理念¶

ADK 的指标方法设计为轻量、标准化，且完全不受监控后端选择的影响。

OpenTelemetry 语义约定： ADK 实现了 OpenTelemetry (OTel) GenAI 语义约定。这确保了指标在标准、可预测的属性和指标名称下进行记录。
OTLP 有线格式： ADK 使用标准 OTLP 格式发送数据，确保你的指标可以无缝集成到任何 OTel 兼容的后端（例如 Prometheus、Datadog、SigNoz、Google Cloud Monitoring）。
注重成本和性能： 在对大量数据进行统计分析时，指标的成本和性能显著优于日志和追踪。ADK 跟踪 LLM 应用程序最关键信号：Token 消耗、请求延迟和工具执行可靠性。
供应商中立的导出： ADK 不会将你锁定在特定的指标管道中。你可以实例化标准的 OTel 计量提供程序，并将数据导出到你的基础设施所需的任何位置。

指标模式¶

启用指标后，ADK 会根据 OpenTelemetry GenAI 语义约定自动检测智能体的生命周期、工作流步骤和工具执行。会发出以下核心指标：

指标名称	类型	描述	关键属性（维度）
`gen_ai.agent.invocation.duration`	Histogram	智能体处理提示词并返回响应的总耗时。	`gen_ai.agent.name`、`error.type`
`gen_ai.tool.execution.duration`	Histogram	智能体调用的单个工具的执行延迟。用于发现慢速外部 API。	`gen_ai.tool.name`、`error.type`
`gen_ai.agent.request.size`	Histogram	发送给智能体的传入请求的大小或复杂度。	`gen_ai.agent.name`
`gen_ai.agent.response.size`	Histogram	智能体生成的最终响应的大小或复杂度。	`gen_ai.agent.name`
`gen_ai.agent.workflow.steps`	Histogram	跟踪智能体完成工作流所进行的迭代步骤或推理循环次数。	`gen_ai.agent.name`

指标导出设置¶

在 ADK Web 中导出指标¶

如果你使用 adk web 或 adk api_server CLI 命令运行智能体，可以配置指标导出。

OTLP 导出¶

要将指标导出到 OTLP 兼容的后端，设置标准的 OTel 环境变量：

export OTEL_EXPORTER_OTLP_METRICS_ENDPOINT="http://your-collector:4318/v1/metrics"
adk web path/to/your/agents_dir

注意： 如果你希望将追踪和日志也发送到同一端点，也可以设置通用的 OTEL_EXPORTER_OTLP_ENDPOINT 环境变量。

GCP 导出¶

要启用向 Google Cloud Monitoring 导出指标，使用 -otel_to_cloud 标志：

adk web -otel_to_cloud path/to/your/agents_dir

程序化指标导出¶

你也可以在应用程序代码中以编程方式配置指标导出。

OTLP 导出设置¶

要启用指标并以编程方式将其导出到 OpenTelemetry Collector（或 OTLP 兼容的后端）：

from google.adk.telemetry.setup import maybe_set_otel_providers
import os

os.environ["OTEL_EXPORTER_OTLP_METRICS_ENDPOINT"] = "http://your-collector:4318/v1/metrics"
os.environ["OTEL_SERVICE_NAME"] = "your-adk-agent"
os.environ["OTEL_RESOURCE_ATTRIBUTES"] = "key1=value1,key2=value2"
maybe_set_otel_providers()

GCP 导出设置¶

要以编程方式将指标导出到 Google Cloud Monitoring，使用 OpenTelemetry Google Cloud 导出器。以下是 Python 示例：

from google.adk.telemetry.google_cloud import get_gcp_exporters
from google.adk.telemetry.setup import maybe_set_otel_providers
import os

gcp_exporters = get_gcp_exporters(
  enable_cloud_metrics = True,
)
os.environ["OTEL_SERVICE_NAME"] = "your-adk-agent"
os.environ["OTEL_RESOURCE_ATTRIBUTES"] = "key1=value1,key2=value2"
maybe_set_otel_providers([gcp_exporters])