记录代理

如需在代理部署后使用 Cloud Logging，请使用以下方法之一：

stdout / stderr：默认情况下（无需任何其他设置），写入 stdout 和 stderr 的日志将分别路由到日志 ID reasoning_engine_stdout 和 reasoning_engine_stderr。但它们必须是文本。
Python 日志记录：内置的 Python 日志记录器可以与 Cloud Logging 集成。与写入 stdout 或 stderr 相比，此方法支持结构化日志，并且需要进行最少的设置。
Cloud Logging 客户端：用户可以编写结构化日志，并可以完全控制日志记录器（例如，设置 logName 和资源类型）。

为代理写入日志

为代理写入日志时，请确定：

severity：例如 info、warn、error
payload：日志的内容（例如文本或 JSON）
其他字段：用于在日志之间建立关联（例如跟踪记录/span、标记、标签）

例如，如需在开发代理时记录每个查询的输入，请执行以下操作：

stdout 或 stderr

from typing import Dict

class MyAgent:

    def set_up(self):
        # No set up required. The logs from stdout and stderr are routed to
        # `reasoning_engine_stdout` and `reasoning_engine_stderr` respectively.
        pass

    def query(self, input: Dict):
        import sys

        print(
            f"input: {input}",
            file=sys.stdout,  # or sys.stderr
        )

Python 日志记录

from typing import Dict

class MyAgent:

    def set_up(self):
        import os
        import google.cloud.logging

        self.logging_client = google.cloud.logging.Client(project="PROJECT_ID")
        self.logging_client.setup_logging(
            name="LOG_ID",  # the ID of the logName in Cloud Logging.
            resource=google.cloud.logging.Resource(
                type="aiplatform.googleapis.com/ReasoningEngine",
                labels={
                    "location": "LOCATION",
                    "resource_container": "PROJECT_ID",
                    "reasoning_engine_id": os.environ.get("K_SERVICE", "").split("-")[-1],
                },
            ),
        )

    def query(self, input: Dict):
        import logging
        import json

        logging_extras = {
            "labels": {"foo": "bar"},
            "trace": "TRACE_ID",
        }

        logging.info( # or .warning(), .error()
            json.dumps(input),
            extra=logging_extras,
        )

Cloud Logging 客户端

from typing import Dict

class MyAgent:

    def set_up(self):
        import os
        import google.cloud.logging

        self.logging_client = google.cloud.logging.Client(project="PROJECT_ID")
        self.logger = self.logging_client.logger(
            name="LOG_ID",  # the ID of the logName in Cloud Logging.
            resource=google.cloud.logging.Resource(
                type="aiplatform.googleapis.com/ReasoningEngine",
                labels={
                    "location": "LOCATION",
                    "resource_container": "PROJECT_ID",
                    "reasoning_engine_id": os.environ.get("K_SERVICE", "").split("-")[-1],
                },
            ),
        )

    def query(self, input: Dict):
        logging_extras = {
            "labels": {"foo": "bar"},
            "trace": "TRACE_ID",
        }

        self.logger.log_struct(
            input,
            severity="INFO",  # or "DEBUG", "WARNING", "ERROR", "CRITICAL"
            **logging_extras,
        )

当代理部署并查询时，它会生成日志条目。例如，代码

remote_agent = agent_engines.create(
    MyAgent(),
    requirements=["cloudpickle==3", "google-cloud-logging"],
)

remote_agent.query(input={"hello": "world"})

将生成如下所示的日志条目：

stdout 或 stderr

{
  "insertId": "67a3bb3b000cc2df444361ab",
  "textPayload": "input: {'hello': 'world'}",
  "resource": {
    "type": "aiplatform.googleapis.com/ReasoningEngine",
    "labels": {
      "location": "LOCATION",
      "resource_container": "PROJECT_ID",
      "reasoning_engine_id": "RESOURCE_ID"
    }
  },
  "timestamp": "2025-02-05T19:25:47.836319Z",
  "logName": "projects/PROJECT_ID/logs/aiplatform.googleapis.com%2Freasoning_engine_stdout",  # or `*_stderr`
  "receiveTimestamp": "2025-02-05T19:25:47.842550772Z"
}

Python 日志记录

{
  "insertId": "1ek9a2jfqh777z",
  "jsonPayload": {"hello": "world"},
  "resource": {
    "type": "aiplatform.googleapis.com/ReasoningEngine",
    "labels": {
      "location": "LOCATION",
      "resource_container": "PROJECT_ID",
      "reasoning_engine_id": "RESOURCE_ID",
    }
  },
  "timestamp": "2025-02-05T20:30:19.348067Z",
  "severity": "INFO",
  "labels": {
    "foo": "bar",
    "python_logger": "root",
  },
  "logName": "projects/PROJECT_ID/logs/LOG_ID",
  "trace": "TRACE_ID",
  "receiveTimestamp": "2025-01-30T21:38:50.776813191Z"
}

Cloud Logging 客户端

{
  "insertId": "1ek9a2jfqh777z",
  "jsonPayload": {"hello": "world"},
  "resource": {
    "type": "aiplatform.googleapis.com/ReasoningEngine",
    "labels": {
      "location": "LOCATION",
      "resource_container": "PROJECT_ID",
      "reasoning_engine_id": "RESOURCE_ID",
    }
  },
  "timestamp": "2025-01-30T21:38:50.776813191Z",
  "severity": "INFO",
  "labels": {"foo": "bar"},
  "logName": "projects/PROJECT_ID/logs/LOG_ID",
  "trace": "TRACE_ID",
  "receiveTimestamp": "2025-01-30T21:38:50.776813191Z"
}

查看代理的日志

您可以使用 Logs Explorer 查看日志条目：

在 Google Cloud 控制台中打开 Logs Explorer。

转到日志浏览器
选择页面顶部的 Google Cloud 项目（对应于 PROJECT_ID）。
在资源类型中，选择 Vertex AI Reasoning Engine。

构建查询

您可以使用 Logs Explorer 逐步构建查询。查询通常是根据以下因素构建的：

时间轴：用于根据时间搜索相关日志条目
范围：用于根据规范属性搜索相关日志条目
- 资源：将其与项目中的其他类型资源区分开来。
  - type：在 Logs Explorer 中显示为“Vertex AI Reasoning Engine”，在日志条目中显示为 "aiplatform.googleapis.com/ReasoningEngine"。
  - labels：对于位置 (LOCATION)、项目 PROJECT_ID 和资源 RESOURCE_ID。
- logName：日志条目所属的日志：
  - 构建时生成的日志条目具有日志 ID reasoning_engine_build。
  - stdout 和 stderr 的日志条目分别具有日志 ID reasoning_engine_stdout 和 reasoning_engine_stderr。
  - 来自 Python 日志记录或 Cloud Logging 客户端的日志条目将具有自定义日志 ID，具体取决于您在为代理写入日志中的代码。
- trace 和 span：用于跟踪查询时的日志。
- severity：日志条目的严重性。
- insertId：日志条目的唯一标识符。
labels：键值对映射，用于提供有关日志条目的其他信息。这些标签可以是用户定义的，也可以是系统定义的，可用于对日志进行分类，并在 Logs Explorer 中更轻松地搜索日志。
payload：日志条目的内容。

以下示例展示了如何使用 RESOURCE_ID 查询已部署代理的所有 INFO 日志：

resource.labels.reasoning_engine_id=RESOURCE_ID AND
severity=INFO

您可以在 Logs Explorer 中查看该日志：

https://console.cloud.google.com/logs/query;query=severity%3DINFO%0Aresource.labels.reasoning_engine_id%3D%22RESOURCE_ID%22;duration=DURATION?project=PROJECT_ID

其中，查询已适当进行网址编码，其他参数如下所示：

DURATION：例如过去 30 分钟的 PT30M（或过去 10 分钟的 PT10M），以及
PROJECT_ID： Google Cloud 项目。

如需了解详情，请参阅使用 Logging 查询语言构建和保存查询。

代理的查询日志

如需以程序化方式查询日志，有两种常见的选项：

结构化查询语言 (SQL)。借助 Log Analytics，您可以查询日志视图或分析视图。
- 日志视图具有与日志条目相对应的固定架构。
- Google Analytics 数据视图具有基于 SQL 查询结果的架构。
Python。通过与您的编程语言（在本例中为 Python）对应的客户端库调用 Cloud Logging API。

Python

from google.cloud import logging

logging_client = logging.Client(project="PROJECT_ID")
logger = logging_client.logger("LOG_ID")  # E.g. "logging_client"
print("Listing entries for logger {}:".format(logger.name))
for entry in logger.list_entries(
    filter_="resource.labels.reasoning_engine_id=RESOURCE_ID"  # Optional
):
    timestamp = entry.timestamp.isoformat()
    print("* {}: {}".format(timestamp, entry.payload))

每个 entry 都对应于一个 LogEntry。如需详细了解 logger.list_entries 的输入实参，请参阅 API 参考文档。

SQL

日志视图：

SELECT *
FROM `PROJECT_ID.LOCATION.BUCKET_ID.LOG_VIEW_ID`

分析视图：

SELECT *
FROM `analytics_view.PROJECT_ID.LOCATION.ANALYTICS_VIEW_ID`