エージェントのロギング

デプロイされたエージェントで Cloud Logging を操作するには、次のいずれかの方法を使用します。

stdout / stderr: デフォルトでは（追加の設定なし）、stdout と stderr に書き込まれたログは、それぞれログ ID reasoning_engine_stdout と reasoning_engine_stderr に転送されます。ただし、テキストであることを必要とする制限があります。
Python ロギング: 組み込みの Python ロガーを Cloud Logging と統合できます。stdout または stderr への書き込みの場合と異なり、構造化ログがサポートされ、最小限の設定で済みます。
Cloud Logging クライアント: ユーザーは構造化されたログを書き込み、ロガーを完全に制御できます（logName とリソースタイプの設定など）。

エージェントのログを書き込む

エージェントのログを書き込む場合は、次のことを決定します。

重大度: info、warn、error など
ペイロード: ログの内容（テキスト、JSON など）
追加のフィールド: ログ間の関連付けに使用（トレース / スパン、タグ、ラベルなど）

たとえば、エージェントを開発するときに各クエリの入力をログに記録するには、次のようにします。

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"
}

エージェントのログを表示する

ログエントリを表示するには、ログエクスプローラを使用します。

Google Cloud コンソールの [ログエクスプローラ] に移動します。

[ログエクスプローラ] に移動
ページ上部で Google Cloud プロジェクト（PROJECT_ID に対応）を選択します。
[リソースの種類] で、[Vertex AI Reasoning Engine] を選択します。

クエリの作成

ログエクスプローラを使用して、クエリを段階的に作成できます。クエリは通常、次の点を考慮して作成されます。

timeline: 時間に基づいて関連するログエントリを検索します。
scope: 正規属性に基づいて関連するログエントリを検索します。
- resource: プロジェクト内の他のタイプのリソースとは分離します。
  - type: ログエクスプローラでは「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: ログエントリの固有識別子。
label: ログエントリに関する追加情報を提供する Key-Value ペアのマップ。ラベルはユーザー定義またはシステム定義にできます。ログを分類し、ログエクスプローラでログを簡単に検索できるようにするために活用できます。
payload: ログエントリの内容。

RESOURCE_ID を使用してデプロイされたエージェントから取得したすべての INFO ログのクエリの例を次に示します。

resource.labels.reasoning_engine_id=RESOURCE_ID AND
severity=INFO

ログエクスプローラで次の場所に表示できます。

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

ここで、クエリは適切に URL エンコードされており、他のパラメータは次のとおりです。

DURATION: 過去 30 分間の PT30M（または過去 10 分間の PT10M）など。
PROJECT_ID: Google Cloud プロジェクト。

詳細については、Logging のクエリ言語を使用してクエリを作成して保存するをご覧ください。

エージェントのログをクエリする

ログをクエリする際のプログラムによる手法には、次の 2 つの一般的なオプションがあります。

構造化クエリ言語（SQL）。ログ分析では、ログビューまたは分析ビューをクエリできます。
- ログビューには、ログエントリに対応する固定のスキーマがあります。
- 分析ビューには、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`

エージェントのロギング コレクションでコンテンツを整理 必要に応じて、コンテンツの保存と分類を行います。

エージェントのログを書き込む

stdout または stderr

Python ロギング

Cloud Logging クライアント

stdout または stderr

Python ロギング

Cloud Logging クライアント

エージェントのログを表示する

クエリの作成

エージェントのログをクエリする

Python

SQL

エージェントのロギング