智能体活动指标¶

Supported in ADKPython v1.32.0Kotlin v0.1.0

智能体开发套件（ADK）提供内置的、与厂商无关的指标收集功能，帮助你了解智能体的性能、成本和使用模式。日志提供了关于发生了什么的详细叙述，而指标则提供聚合的定量数据，用于回答事情发生的频率和速度。

指标理念¶

ADK 的指标方法设计为轻量级、标准化，并且完全与你选择的监控后端无关。

OpenTelemetry 语义约定： ADK 实现了 OpenTelemetry (OTel) GenAI 语义约定。这确保了指标以标准、可预测的属性和指标名称进行记录。
OTLP 传输格式： ADK 使用标准的 OTLP 格式发出数据，确保你的指标能够无缝集成到任何 OTel 兼容的后端（如 Prometheus、Datadog、SigNoz、Google Cloud Monitoring）。
成本和性能优先： 在对大量数据进行分析时，指标的成本和性能显著优于日志或追踪。ADK 跟踪 LLM 应用程序最关键的信号：令牌消耗、请求延迟和工具执行可靠性。
厂商中立导出： 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])

Kotlin 编程设置¶

在 Kotlin 中，ADK 使用标准的 GlobalOpenTelemetry 管理指标。使用 MeterProvider 配置 OpenTelemetry SDK 即可启用指标收集。

OTLP 导出设置¶

要启用指标并将其导出到 OpenTelemetry Collector，请使用适当的指标导出器配置 OpenTelemetry SDK：

// 1. Configure OpenTelemetry (Traces)
// ADK Kotlin uses GlobalOpenTelemetry to resolve its tracer on the JVM.
val spanExporter = OtlpGrpcSpanExporter.builder().setEndpoint("http://localhost:4317").build()

val resource =
    Resource.getDefault()
        .merge(
            Resource.create(
                Attributes.of(AttributeKey.stringKey("service.name"), "my-kotlin-agent"),
            ),
        )

val tracerProvider =
    SdkTracerProvider.builder()
        .addSpanProcessor(BatchSpanProcessor.builder(spanExporter).build())
        .setResource(resource)
        .build()

OpenTelemetrySdk.builder().setTracerProvider(tracerProvider).buildAndRegisterGlobal()

// 2. Optional: Configure ADK Telemetry behavior
// Enable capturing full message content in traces (use with caution in production)
TelemetryConfig.captureMessageContent = true

// 3. Initialize Agent and Runner with LoggingPlugin for console output
val agent = LlmAgent(name = "my_agent", model = Gemini(name = "gemini-flash-latest"))

val runner =
    InMemoryRunner(agent = agent, pluginManager = PluginManager(listOf(LoggingPlugin())))

// The runner will now automatically emit traces via GlobalOpenTelemetry
// and log activity to the console via the LoggingPlugin.
runner.run(
    userId = "user123",
    sessionId = "session456",
    newMessage = Content.fromText(Role.USER, "Hello!"),
)