此页面由 Cloud Translation API 翻译。

使用 OpenTelemetry 对 ADK 应用进行插桩

本文档介绍了如何检测使用智能体开发套件 (ADK) 框架构建的 AI 智能体。借助这种利用 OpenTelemetry 的插桩，您可以收集用户提示、代理响应和代理选择。

ADK 框架本身已使用 OpenTelemetry 进行插桩，可捕获智能体执行过程中关键步骤的遥测数据。这可提供开箱即用的宝贵应用可观测性。不过，这种可观测性可能无法满足您应用的使用情形。您可以使用 OpenTelemetry 添加其他插桩库，以捕获应用其他部分的遥测数据，也可以使用自己的自定义插桩来捕获应用特有数据，从而获得更精细的可观测性。

例如，在您的应用中，您可以编写插桩代码来执行以下操作：

跟踪代理调用的工具的资源消耗情况。
跟踪特定于应用的验证失败、业务规则违规或自定义错误恢复机制。
根据特定领域的标准跟踪客服人员回答的质量得分。

对生成式 AI 应用进行插桩以收集遥测数据

如需对 AI 代理进行插桩以收集日志、指标和跟踪记录数据，请执行以下操作：

安装 OpenTelemetry 软件包
配置 OpenTelemetry 以收集和发送遥测数据
编写自定义入口点以注入配置的 OpenTelemetry

本部分的其余内容将介绍上述步骤。

安装 OpenTelemetry 软件包

添加以下 OpenTelemetry 插桩和导出器软件包：

pip install 'opentelemetry-instrumentation-google-genai' \
  'opentelemetry-instrumentation-sqlite3' \
  'opentelemetry-exporter-gcp-logging' \
  'opentelemetry-exporter-gcp-monitoring' \
  'opentelemetry-exporter-otlp-proto-grpc' \
  'opentelemetry-instrumentation-vertexai>=2.0b0'

日志和指标数据使用 Cloud Logging API 或 Cloud Monitoring API 发送到您的 Google Cloud 项目。opentelemetry-exporter-gcp-logging 和 opentelemetry-exporter-gcp-monitoring 库会调用这些 API 中的端点。

跟踪数据使用支持 OTLP 格式的遥测 (OTLP) API 发送到 Google Cloud 。通过此端点接收的数据也会以 OTLP 格式存储。 opentelemetry-exporter-otlp-proto-grpc 库会调用遥测 (OTLP) API 端点。

配置 OpenTelemetry 以收集和发送遥测数据

在 ADK 代理的初始化代码中，添加代码以将 OpenTelemetry 配置为捕获遥测数据并将其发送到您的 Google Cloud 项目：

如需查看完整示例，请点击更多，然后选择在 GitHub 上查看。

def setup_opentelemetry() -> None:
    credentials, project_id = google.auth.default()
    resource = Resource.create(
        attributes={
            SERVICE_NAME: "adk-sql-agent",
            # The project to send spans to
            "gcp.project_id": project_id,
        }
    )

    # Set up OTLP auth
    request = google.auth.transport.requests.Request()
    auth_metadata_plugin = AuthMetadataPlugin(credentials=credentials, request=request)
    channel_creds = grpc.composite_channel_credentials(
        grpc.ssl_channel_credentials(),
        grpc.metadata_call_credentials(auth_metadata_plugin),
    )

    # Set up OpenTelemetry Python SDK
    tracer_provider = TracerProvider(resource=resource)
    tracer_provider.add_span_processor(
        BatchSpanProcessor(
            OTLPSpanExporter(
                credentials=channel_creds,
                endpoint="https://telemetry.googleapis.com:443/v1/traces",
            )
        )
    )
    trace.set_tracer_provider(tracer_provider)

    logger_provider = LoggerProvider(resource=resource)
    logger_provider.add_log_record_processor(
        BatchLogRecordProcessor(CloudLoggingExporter())
    )
    logs.set_logger_provider(logger_provider)

    event_logger_provider = EventLoggerProvider(logger_provider)
    events.set_event_logger_provider(event_logger_provider)

    reader = PeriodicExportingMetricReader(CloudMonitoringMetricsExporter())
    meter_provider = MeterProvider(metric_readers=[reader], resource=resource)
    metrics.set_meter_provider(meter_provider)

    # Load instrumentors
    SQLite3Instrumentor().instrument()
    # ADK uses Vertex AI and Google Gen AI SDKs.
    VertexAIInstrumentor().instrument()
    GoogleGenAiSdkInstrumentor().instrument()

编写自定义入口点以使用配置的 OpenTelemetry

如需使用 OpenTelemetry 进行插桩，请为 ADK 应用创建自定义入口点。自定义入口点必须在启动 ADK 代理之前配置 OpenTelemetry。

在示例应用中，main 方法充当自定义入口点，用于初始化 OpenTelemetry，然后启动 FastAPI 服务器，以便您与代理互动。

如需查看完整示例，请点击更多，然后选择在 GitHub 上查看。

def main() -> None:
    # Make sure to set:
    # OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true
    # OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
    # in order to full prompts and responses and logs messages.
    # For this sample, these can be set by loading the `opentelemetry.env` file.
    setup_opentelemetry()

    # Call the function to get the FastAPI app instance.
    # Ensure that the agent director name is the name of directory containing agent subdirectories,
    # where each subdirectory represents a single agent with __init__.py and agent.py files.
    # For this example this would be the current directory containing main.py.
    # Note: Calling this method attempts to set the global tracer provider, which has already been
    # set by the setup_opentelemetry() function.
    app = get_fast_api_app(
        agents_dir=AGENT_DIR,
        session_service_uri=SESSION_DB_URL,
        allow_origins=ALLOWED_ORIGINS,
        web=SERVE_WEB_INTERFACE,
    )

    # Lauch the web interface on port 8080.
    uvicorn.run(app, host="0.0.0.0", port=int(os.environ.get("PORT", 8080)))

下载并运行示例应用

此示例代码实现了一个使用 ADK 构建的生成式 AI 代理。该代理使用 OpenTelemetry 进行插桩，并配置为将指标、跟踪记录和日志发送到您的 Google Cloud 项目。发送到您项目的遥测数据包括生成式 AI 提示和回答。

ADK 智能体角色

生成式 AI 代理定义为可完全访问临时 SQLite 数据库的 SQL 专家。该智能体使用智能体开发套件构建，并使用 SQLDatabaseToolkit 访问数据库。数据库最初为空。

准备工作

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.
Enable the Vertex AI, Telemetry, Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.
Enable the APIs
如需获得让示例应用写入日志、指标和跟踪记录数据所需的权限，请让管理员为您授予项目的以下 IAM 角色：
- Cloud Telemetry Traces Writer (roles/telemetry.tracesWriter)
- Logs Writer (roles/logging.logWriter)
- Monitoring Metric Writer (roles/monitoring.metricWriter)
- Vertex AI User (roles/aiplatform.user)

启动应用

如需启动示例应用，请执行以下操作：

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

克隆代码库：

git clone https://github.com/GoogleCloudPlatform/opentelemetry-operations-python.git

转到示例目录：

cd opentelemetry-operations-python/samples/adk-sql-agent

创建虚拟环境并运行示例：

python -m venv venv/
source venv/bin/activate
pip install -r requirements.txt
env $(cat opentelemetry.env | xargs) python main.py

应用会显示类似以下内容的消息：

Appplication startup complete
Uvicorn running on http://0.0.0.0:8080

如需与代理互动，请在浏览器中打开上一步中列出的地址。
展开选择代理，然后从代理列表中选择 sql_agent。

与代理互动

如需与代理互动，请向其提问或下达指令。例如，您可以提出以下问题：

What can you do for me ?

同样，由于 sql_agent 具有 SQL 专家的角色，因此您可以要求它为您的应用创建表，并编写查询来操作所创建的表。代理只能创建由在运行应用的机器上创建的 .db 文件支持的临时数据库。

以下示例展示了 sql_agent 与用户之间的互动：

Create a table for me to store weather data and also insert sample data in
the table. At the end show all data in the table you created.

与 sql_agent 的互动显示。

生成式 AI 智能体执行的操作不是确定性的，因此您可能会看到针对同一提示的不同回答。

退出应用

如需退出应用，请在用于启动应用的 shell 中输入 Ctrl-C。

查看跟踪记录、指标和日志

本部分介绍如何查看生成式 AI 事件。

准备工作

如需获得查看日志、指标和跟踪记录数据所需的权限，请让管理员为您授予项目的以下 IAM 角色：

Logs Viewer (roles/logging.viewer)
Monitoring Viewer (roles/monitoring.viewer)
Cloud Trace User (roles/cloudtrace.user)

如需详细了解如何授予角色，请参阅管理对项目、文件夹和组织的访问权限。

您也可以通过自定义角色或其他预定义角色来获取所需的权限。

查看遥测数据

如需查看应用创建的生成式 AI 事件，请使用 Trace 探索器页面：

在 Google Cloud 控制台中，前往 Trace 探索器页面：
转到 Trace 探索器

您也可以使用搜索栏查找此页面。
在工具栏中，依次选择添加过滤条件、Span 名称和 call_llm。

下面展示了过滤数据后的 Trace 探索器页面：

如果您之前从未使用过 Cloud Trace，Google Cloud Observability 需要创建一个数据库来存储跟踪记录数据。创建数据库可能需要几分钟时间，在此期间，您无法查看任何跟踪记录数据。
如需浏览 span 和日志数据，请在 Span 表格中选择 span。

系统会打开详细信息页面。此页面会显示关联的跟踪记录及其 span。页面上的表格会显示您所选 span 的详细信息。这些信息包括：
- GenAI 标签页会显示生成式 AI 智能体的事件。如需详细了解这些事件，请参阅查看生成式 AI 事件。
  
  以下屏幕截图展示了一条跟踪记录，其中一个 span 的名称为 call_llm。该 span 会调用为该代理提供支持的 LLM（大语言模型）。在此示例中，它是 Gemini。 Gemini span 包含以下生成式 AI 事件：
- 日志和事件标签页会列出与该 span 关联的日志条目和事件。如果您想在 Logs Explorer 中查看日志数据，请在该标签页的工具栏中选择查看日志。
  
  日志数据包含 sql_agent 的回答。例如，对于示例运行，JSON 载荷包含以下内容：
```
{
  "logName": "projects/my-project/logs/otel_python_inprocess_log_name_temp",
  "jsonPayload": {
    "content": {
      "role": "model",
      "parts": [
        {
          "executable_code": null,
          "inline_data": null,
          "thought": null,
          "video_metadata": null,
          "code_execution_result": null,
          "function_response": null,
          "thought_signature": null,
          "text": "Okay, I will create a table named `weather` with columns `id`, `city`, `temperature`, and `date`. Then I will insert some sample rows into the table and display all the data in the table.\n",
          "file_data": null,
          "function_call": null
        }
      ]
    }
  },
  ...
}
```

该示例经过插桩，可将指标数据发送到您的 Google Cloud 项目，但不会生成任何指标。

使用 OpenTelemetry 对 ADK 应用进行插桩 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

对生成式 AI 应用进行插桩以收集遥测数据

安装 OpenTelemetry 软件包

配置 OpenTelemetry 以收集和发送遥测数据

编写自定义入口点以使用配置的 OpenTelemetry

下载并运行示例应用

ADK 智能体角色

准备工作

启动应用

与代理互动

退出应用

查看跟踪记录、指标和日志

准备工作

查看遥测数据

使用 OpenTelemetry 对 ADK 应用进行插桩