エージェントを監視する

Overview

このガイドでは、エージェントのパフォーマンスと配置の健全性を監視する方法を学習できます。

エージェントサンドボックスは実行中にログを生成し、エージェントの動作を監視し、問題を診断するために使用できます。これらのログは、次の方法で検索できます。

APIまたは CLIエージェントログを使用する: stdout/stderr 出力、print() ステートメント、フレームワークデバッグ出力を含むエージェントの実行時ログを取得します。
配置イベントログにAPI を使用: 構造化配置イベントログにアクセスして、配置の動作を追跡し、障害を調査し、ライフサイクルの移行を検証します。

配置されたエージェントのライブヘルスを確認するには、agentengine status コマンドまたはプラットフォームUIのワークスペースのヘルスカードを使用します。

特定のエージェントの実行でレイテンシや予期しない動作をデバッグするには、「エージェントの実行トレースの調査」を参照してください。

エージェントの実行ログの表示

MongoDB Atlas Agent は、エンジンの stdout/stdar 出力、print() ステートメント、logging 呼び出し、フレームワークデバッグ出力をキャプチャし、配置されたエージェントから S3 に保存します。これらのログは、プラットフォームUI、 API、または CLI を使用して検索できます。

UI の使用

UIでログを表示するには、次の手順を実行します。

左側のナビゲーションバーから Workspaces を選択し、表示するワークスペースをクリックします。
インタラクティブログビューを開くには、Logsタブをクリックします。
15m1h、、または6h ボタンを選択して、表示する期間を調整します。タイムゾーンセレクターを使用してタイムゾーンを変更することもできます。ログをより一定期間表示するには、ログのエクスポート機能を使用します。
ログをフィルタリングするには、Level、Source、Service のドロップダウンメニューからオプションを選択します。次に、Search をクリックしてフィルターを適用します。レベルフィルターとソースフィルターは完全一致を返すため、INFOを選択すると INFO エントリのみが返され、INFO 以上の重大度は返されません。

APIの使用

次のエンドポイントを使用して、クエリエージェントの実行ログを記録します。

GET /api/v1/projects/{id}/agent-logs

クエリするプロジェクトのオブジェクトIDを {id} 値として渡します。呼び出し元は、そのプロジェクトの組織に属している必要があります。

次のクエリパラメーターを使用できます。

Parameter	必須	説明
`workspace_id`	はい	ログを検索するワークスペース識別子。
`start_time`	No	RFC3339 開始時間。デフォルトは 1 時間前です。 `start_time` と `end_time` の範囲は 6 時間を超えることはできません。
`end_time`	No	RFC3339 終了時間。デフォルトはになりました。
`level`	No	ログレベルがと完全に一致するようにします。このパラメータは、`DEBUG`、`INFO`、`WARNING`、または `ERROR` を受け入れます。
`execution_id`	No	実行ID （完全一致）でフィルタリングします。
`session_id`	No	セッションID （完全一致）でフィルタリングします。
`source`	No	ログソース : `stdout`、`stderr`、`python-logging`、または `node-logging` でフィルタリングします。
`service`	No	サービスでフィルタリングします: `agent` または `tool`。
`search`	No	`message` または `bootId`フィールドで、大文字と小文字を区別しない部分文字列の一致。
`limit`	No	返されるエントリの最大数。デフォルトは `500`、最大 `5000` です。
`cursor`	No	以前の応答によって返された不変のページ分割カーソル。
`order`	No	結果のソート順。このパラメータは `asc` または `desc` を受け入れます。デフォルトは `asc` です。
`tail`	No	時間範囲の先頭からページ分割する代わりに、最新のエントリを返すかどうかを指定するブール値。 `cursor` パラメータと組み合わせることはできません。

結果は、カーソルを使用してページ分割されます。各応答には、応答が最後のページでない限り、 nextCursorフィールドと hasMoreブール値が含まれます。次のページを取得するには、nextCursor の値を次のリクエストの cursor パラメータとして渡します。

logs 配列内の各ログエントリには次のフィールドが含まれています。

フィールド	説明
`timestamp`	ログエントリが記録された時間（ RFC3339形式）。
`level`	ログレベル: `DEBUG`、`INFO`、`WARNING`、または `ERROR`。
`message`	ログメッセージのコンテンツ。
`source`	ログの元 : `stdout`、`stderr`、`python-logging`、または `node-logging` 。
`service`	ログを生成したサービス。
`tenantId`	実行中のエージェントを所有するテナント。
`executionId`	ログエントリに関連付けられた実行。
`sessionId`	ログエントリに関連付けられたセッション。
`workspaceId`	ログエントリに関連付けられたワークスペース。
`traceId`	ログエントリに関連付けられたトレース識別子。
`bootId`	ログエントリを生成したポッド起動の識別子。
`logger`	ロガー名（ログが`logging` 呼び出しから発生した場合）。
`podName`	ログを生成したKubernetesポッド。
`fields`	ログエントリに添付される追加の構造化キー値フィールド。

CLI の使用

エージェントの実行ログを検索するには、次の CLI コマンドを使用します。

agentengine logs [flags]

コマンドは、現在のディレクトリの.agentengine/ 状態ファイルからワークスペースを解決します。別のワークスペースをターゲットにするには、名前付きコンテキストとともに--context フラグを渡すか、--workspace-id フラグを、--project-id --org-id、--base-url とともに渡します。ワークスペースの管理の詳細については、「ワークスペースの管理」を参照してください。

次のフラグを使用できます。

Flag	説明
`--session-id`	セッションIDでフィルタリングします。
`--execution-id`	実行IDでフィルタリングします。
`--source`	ソースサンドボックスでフィルタリングします: `agent` または `tool`。カンマまたはスペースで区切られたリストを受け入れます。
`--level`	完全に一致するログレベルは、`debug`、`info`、`warn`、または `error` です。カンマまたはスペースで区切られたリストを受け入れます。
`--grep`	ログメッセージの、大文字と小文字を区別しない部分文字列検索。グローバルまたは正規表現ではありません。
`--since`	期間としての開始時間（例: 、`30m`、`2h`）または RFC3339 タイムスタンプ。デフォルトは `1h` です。最大 `6h`。
`--until`	期間または RFC3339 タイムスタンプとしての終了時間。デフォルトはになりました。
`--tail`	返される最新エントリの最大数。デフォルトは `500` です。上限は `5000` ですが、`--all` を使用すると時間範囲内のすべてのログエントリを取得できます。
`--all`	時間範囲内のすべてのログを取得し、すべてのページを自動的にページ分割します。
`-f`, `--follow`	新しいログの継続的なポーリング。
`--json`	人間が判読できる形式ではなく、 JSONとしてログを出力します。
`--workspace-id`	ターゲットにするワークスペースID 。 `--project-id`、`--org-id`、`--base-url` と組み合わせるか、ワークスペースが登録されているディレクトリで使用する必要があります。
`--project-id`	プロジェクトID。 `--workspace-id` と併用されます。
`--org-id`	組織ID。 `--workspace-id` と併用されます。
`--base-url`	プラットフォームベースURL。 `--workspace-id` と併用されます。
`--workspace`	単一リポジトリで、はルート `agent.yaml` から名前で特定のワークスペースを選択します。
`--context`	ワークスペースIDの代わりに使用するプラットフォームターゲットの指定。利用可能なコンテキストを確認するには、`agentengine context list` を実行します。

例

このセクションでは、一般的なログ検索タスク用の CLI コマンドの例を示します。

次のコマンドは、過去 1 時間のログを検索します。

agentengine logs

次のコマンドは、ライブログが書き込まれるときに追跡します。

agentengine logs --follow

次のコマンドは、エージェントサンドボックスサービスからエラーレベルのログのみを検索します。

agentengine logs --source agent --level error

次のコマンドは、過去 30 分間のログで部分文字列を検索します。

agentengine logs --grep "connection refused" --since 30m

次のコマンドは、過去 6 時間のすべてのログを検索します。

agentengine logs --all --since 6h

未加工のランタイムログのエクスポート

6 時間以上のランタイムログを表示するには、エージェントまたはツールサービスの未加工のログをエクスポートします。エクスポートされるログには最大 24 時間のデータが含まれ、 gzip 圧縮されたJSON typesファイルとしてダウンロードできます。

UI の使用

UIから未加工のランタイムログをエクスポートするには、次の手順を実行します。

左側のナビゲーションバーから Workspaces を選択し、表示するワークスペースをクリックします。
インタラクティブログビューを開くには、Logsタブをクリックします。
Raw エクスポートダイアログを開くには、Export をクリックします。
Service ドロップダウンメニューから [Agent または Tool を選択します。
[Time period ドロップダウンメニューから、過去の 6、12、または 24 時間の事前設定された範囲を選択するか、カスタム範囲を指定します。カスタム範囲は 24 時間を超えることはできません。次に、Time zone ドロップダウンメニューからタイムゾーンを選択します。
ログファイルをダウンロードするには、Export をクリックします。

CLI の使用

未加工のランタイムログをエクスポートするには、次の CLI コマンドを使用します。

agentengine logs export --service <agent|tool> [flags]

次のフラグを使用できます。

Flag	説明
`--service`	（必須）エクスポートするランタイムサービス。または`agent` `tool`を指定できます。
`--since`	開始時間。期間または RFC3339 タイムスタンプとして渡すことができます。デフォルトは `24h` です。 `--since` と `--until` の値の範囲は 24 時間を超えることはできません。
`--until`	期間または RFC3339 タイムスタンプとしての終了時間。デフォルトは現在の時刻です。
`-o`, `--output`	出力ファイルパス。デフォルトは `agent-logs-<service>-<end-time>.jsonl.gz` です。コマンドは、このパスにある既存のファイルを上書きしません。
`--workspace-id`	ターゲットにするワークスペースID 。 `--project-id`、`--org-id`、`--base-url` と組み合わせるか、ワークスペースが登録されているディレクトリで使用する必要があります。
`--project-id`	プロジェクトID。 `--workspace-id` と併用されます。
`--org-id`	組織ID。 `--workspace-id` と併用されます。
`--base-url`	プラットフォームベースURL。 `--workspace-id` と併用されます。
`--workspace`	単一リポジトリで、はルート `agent.yaml` から名前で特定のワークスペースを選択します。
`--context`	ワークスペースIDの代わりに使用するプラットフォームターゲットの指定。利用可能なコンテキストを確認するには、`agentengine context list` を実行します。

コマンドはダウンロードをアトミックに書込むため、エクスポートが失敗したり中断された場合でも、宛先に部分的なファイルが残ることはありません。

次のコマンドは、過去の 24 時間のエージェントサービスログをエクスポートします。

agentengine logs export --service agent

次のコマンドは、6 時間のツールサービスログを指定されたファイルにエクスポートします。

agentengine logs export --service tool --since 6h --output logs.jsonl.gz

ログ形式

エージェントサンドボックスは構造化されたJSONレコードとしてログを出力します。以下の表は、各レコードのフィールドを説明したものです。

フィールド	説明
`timestamp`	ログがいつ発行されたかを示す ISO 8601 タイムスタンプ
`level`	ログ重大度レベル（`DEBUG`、`INFO`、`WARNING`、`ERROR` など）
`logger`	レコードを出力したPythonロガーの名前
`message`	人間が判読できるログメッセージのテキスト
`service`	ログのソース。`agent` または `tool` になります
`tenantId`	実行中のエージェントを所有するテナントの識別子
`workspaceId`	エージェントが配置されるワークスペースの識別子
`executionId`	現在実行されているエージェントの識別子
`sessionId`	現在のセッションの識別子
`podName`	ログを発行したコンテナのKubernetesポッド名
`source`	ログエントリを生成したストリーム。`stdout` または `stderr` 可能
`fields`	ログイベントに関する構造化メタデータを含むキーと値のペアのマップ

次の例は、単一の構造化ログレコードの形式を示しています。

{
  "timestamp": "2025-10-15T14:32:07.123456Z",
  "level": "INFO",
  "logger": "agent.executor",
  "message": "Tool call completed",
  "service": "tool",
  "tenantId": "t-abc123",
  "workspaceId": "ws-def456",
  "executionId": "exec-789xyz",
  "sessionId": "sess-uvw012",
  "podName": "tool-ws-def456-5b8d9f-jklmn",
  "source": "stdout",
  "fields": {
    "toolName": "search",
    "durationMs": 243
  }
}

配置イベントの表示

MongoDB Atlas Agent Engine は、各配置の構造化されたイベントログを記録し、作成から完了までのすべての状態遷移をキャプチャします。配置イベントログを使用して、配置の動作を追跡し、障害を調査し、予想されるライフサイクルの移行が発生したことを確認できます。イベントログには、プラットフォームUI、 CLI、 API のいずれかを使用してアクセスできます。

各イベントには、次のフィールドが含まれています。

フィールド	説明
`category`	イベントをトリガーしたライフサイクル移行のカテゴリまたはステージです。指定できる値は、`lifecycle`、`secret_sync`、`cr_create`、`oe_rollout`、`aer_rollout`、`tool_pod_rollout`、`memory_rollout`、`deploy_diagnostic`、`post_deploy_health` です。
`component`	イベントに関連付けられた配置コンポーネント。
`reason`	イベントのマシンが判読可能な理由コード。
`message`	イベントの人間が判読可能な説明。
`condition_ref`	イベントに関連付けられた条件（`Available` や `SecretsReady` など）。

UI の使用

プラットフォームUI には、アクティブと完了の両方を含むすべての配置の配置ページにイベントログタブが表示されます。

、、または pendingであるアクティブな配置では、イベントはin_progresscleaning_up SSE を介してリアルタイムでストリーミングされます。
完了した配置の場合、カードは REST エンドポイントから完全なイベント履歴を読み込みます。

各イベント行には、UTC タイムスタンプ、重大度レベル（info、success、warn、または error）、ライフサイクルステージ、コンポーネント、メッセージが表示されます。イベントはレベル別にフィルタリングして、ビューを絞り込むことができます。

CLI の使用

特定のデプロイのイベントログをで表示するには、agentengine deploy logs コマンドを使用します。詳しくは、「デプロイメントイベントログの表示」を参照してください。

また、-f フラグとagentengine deploy get を併用すると、アクティブな配置中にイベントをリアルタイムでストリーミングできます。詳細については、「配置ステータスの確認」を参照してください。

APIの使用

配置イベントを直接クエリするには、次のAPIエンドポイントを使用します。

GET /api/v1/projects/{project_id}/deployments/{deployment_id}/events

結果は、カーソルを使用してページ分割されます。ページ分割を制御するには、after と limit クエリパラメータを使用します。 limit のデフォルトは 100 であり、100 を超えることはできません。

ワークスペースのヘルスチェック

配置が成功した後は、配置されたエージェントのライブヘルスをいつでも確認できます。ワークスペースのヘルスビューには、各エージェントコンポーネントの現在の読み取り状況、準備完了のレプリカ数、ヘルスが最後にチェックされた日時を示すタイムスタンプが表示されます。

UI の使用

プラットフォームUIのワークスペースの概要ページには、ライブ配置のヘルスカードが含まれています。カードには、ステータス、準備完了レプリカ、理由など、コンポーネントごとの健全性が表示されます。 [ 更新 ] をクリックして、いつでも現在のヘルスを再取得できます。最後にチェックされたタイムスタンプは、ヘルスが最後に取得された日時を示します。

CLI の使用

配置されたエージェントのライブヘルスを表示するには、次のコマンドを実行します。

agentengine status

次のの例に示すように、コマンドはワークスペースのヘルスエンドポイントを呼び出し、その結果をサマリーとしてレンダリングします。

✓ my-agent is ready
summary
  deployment:  deploy-55996f39 (succeeded 21h ago)
  readiness:   4/4 components ready
  health:      healthy (checked just now)
  invoke:      https://<base-url>/api/v1/projects/<project-id>/workspaces/<workspace-id>/invoke
  stream:      https://<base-url>/api/v1/projects/<project-id>/workspaces/<workspace-id>/invokeStream
  dashboard:   https://<base-url>/project/<project-id>/workspaces/<workspace-id>/deployments
components
  Orchestration Engine      healthy (2 replicas)  [scope: project]
  Agent Sandbox             healthy (4 replicas)  [scope: workspace]
  Tool Sandbox              healthy (4 replicas)  [scope: workspace]
  Secrets                   healthy  [scope: workspace]

追加の配置とランタイムの詳細を含めるには --verbose フラグを渡します。または、完全なステータスをJSONとして出力するには、--json を渡します。

ポリシー拒否の表示

ObservabilityプラットフォームUIのページにはPolicy denials タイルが含まれています。タイルには、選択した時間ウィンドウでポリシーエンジンが拒否した呼び出しの数が表示されます。タイルを使用して、ポリシーによって繰り返しブロックされるエージェントを見つけられます。これは、エージェントが不正なワークを試みたか、またはポリシーがワークロードに対して制限的すぎることを示します。タイルには、組織とプロジェクトのデータのみが表示されます。

[] タイルは、AUTHORIZED_TOOLS ポリシータイプが生成する拒否と、実行およびセッション予算ポリシーが生成する拒否をカウントします。タイルは、AUTHORIZED_MODELS ポリシータイプが生成する拒否をカウントしません。各ポリシータイプの詳細については、「ポリシータイプ」を参照してください。

CLI デバッグログの表示

すべての agentengine コマンドは構造化されたJSONログファイルをマシン上のプラットフォーム固有のディレクトリに書込みます。 CLI は 20 の最新のログファイルを保持します。コマンドが失敗した場合、最後の stderr 行にはそのコマンドのログファイルへのパスが含まれます。

次の表は、プラットフォーム別のログロケーションを示しています。

プラットフォーム	パス
MacOS	`~/Library/Logs/agentengine/agentengine-<timestamp>-<pid>.log`
Linux	`${XDG_STATE_HOME:-~/.local/state}/agentengine/logs/`
Windows	`%LOCALAPPDATA%\agentengine\Logs\`

ログファイルのパスを上書きするには、--log-file フラグまたは AGENTENGINE_LOG_FILE 環境変数を使用します。次の環境変数もログの動作を制御します。

AGENTENGINE_LOG_LEVEL ファイルの冗長を設定する
AGENTENGINE_NO_LOG は、ファイルのログ記録を無効にします
AGENTENGINE_LOG_MAX_FILES は、保持されたログファイルの数を設定します
AGENTENGINE_NO_LOG_PRUNE は自動保持プルーニングを無効にします

CLI ログファイルの一覧表示

すべての CLIログファイルを最新順にソートして一覧表示するには、次のコマンドを実行します。

agentengine debug logs list [--json]

各行には、ファイル名と実行されたコマンドが表示されます。 --json フラグを渡すと、schema_version、status、logs 配列を持つマシンが判読可能なオブジェクトが返されます。配列の各エントリには、name、path、modified_at、size_bytes、command が含まれています。

CLI ログファイルの表示

ログファイルの内容を印刷するには、次のコマンドを実行します。

agentengine debug logs get [<logfile>] [--last] [--pretty]

agentengine debug logs list で表示されるログファイル名を渡すか、--last を使用して最新のログを出力します。出力は、デフォルトでは未加工のJSON行として形式されます。各レコードの形式と色付けを行うには、--pretty フラグを渡します。

次の例では、agentengine debug logs コマンドを使用してログファイルを一覧表示して表示します。

agentengine debug logs list
agentengine debug logs get agentengine-2026-05-13T11-43-57Z-12345.log
agentengine debug logs get --last --pretty

追加リソース

このガイドで説明されているAPIエンドポイントの詳細については、 APIドキュメントを参照してください。

戻る

Atlas のロール権限

エージェントの実行トレースの調査

エージェントを監視する

Overview

エージェントの実行ログの表示

UI の使用

APIの使用

CLI の使用

例

未加工のランタイム ログのエクスポート

UI の使用

CLI の使用

ログ形式

配置イベントの表示

UI の使用

CLI の使用

APIの使用

ワークスペースのヘルスチェック

UI の使用

CLI の使用

ポリシー拒否の表示

CLI デバッグ ログの表示

CLI ログファイルの一覧表示

CLI ログファイルの表示

追加リソース

未加工のランタイムログのエクスポート

CLI デバッグログの表示