监控代理

Overview

在本指南中，您可以学习；了解如何监控代理的性能和部署的运行状况。

代理沙箱在执行期间会生成日志，您可以使用该日志监控代理行为和诊断问题。您可以通过以下方式检索这些日志：

使用API或CLI代理日志：检索代理运行时日志，包括 stdout/stderr 输出、print() 语句和框架调试输出。
使用API记录部署事件日志：访问结构化部署事件日志以跟踪部署行为、调查故障并验证生命周期转换。

要检查已部署代理的实时运行状况，请使用 agentengine status 命令或平台用户界面中的工作区运行状况卡。

要调试特定代理运行中的延迟或意外行为，请参阅检查代理执行跟踪。

查看代理运行时日志

MongoDB Atlas助手引擎从已部署的助手中捕获 stdout/stderr 输出、print() 语句、logging 调用和框架调试输出，并将它们存储在 S3 中。您可以使用平台用户界面、 API或CLI检索这些日志。

使用用户界面

要在用户界面上查看日志，请执行以下步骤：

从左侧导航栏中选择 Workspaces，然后单击要查看的工作区。
单击 Logs标签页打开交互式日志查看器。
选择 15m、1h 或 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 开始时间。默认为一小时前。 `start_time` 和 `end_time` 之间的范围不能超过六小时。
`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`	生成日志条目的 pod 启动标识符。
`logger`	记录器名称（如果日志源自 `logging` 调用）。
`podName`	生成日志的Kubernetes Pod。
`fields`	附加到日志条目的其他结构化键值字段。

使用CLI

使用以下CLI命令检索代理运行时日志：

agentengine logs [flags]

该命令从当前目录的 .agentengine/ 状态文件解析工作区。要以不同的工作区为目标，请传递 --context 标志与命名上下文，或将 --workspace-id 标志与 --project-id、--org-id 和 --base-url 一起传递。有关管理工作区的更多信息，请参阅管理工作区。

以下标志可用：

标记	说明
`--session-id`	按会话ID筛选。
`--execution-id`	按执行ID筛选。
`--source`	按源沙箱筛选：`agent` 或 `tool`。接受以逗号或空格分隔的列表。
`--level`	要完全匹配的日志级别：`debug`、`info`、`warn` 或 `error`。接受以逗号或空格分隔的列表。
`--grep`	对日志消息进行不区分大小写的子字符串搜索。不是 glob 或正则表达式。
`--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命令示例。

以下命令检索过去一小时的日志：

agentengine logs

以下命令会在写入实时日志时对其进行跟踪：

agentengine logs --follow

以下命令仅从代理沙盒服务中检索错误级别的日志：

agentengine logs --source agent --level error

以下命令在日志中搜索最近 30 分钟的子字符串：

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

以下命令检索过去六个小时内的所有日志：

agentengine logs --all --since 6h

导出原始运行时日志

要查看超过六小时的运行时日志，您可以导出代理或工具服务的原始日志。导出的日志最多包含 24 小时的数据，您可以将其下载为 gzip 压缩的JSON Lines文件。

使用用户界面

要从用户界面导出原始运行时日志，请执行以下步骤：

从左侧导航栏中选择 Workspaces，然后单击要查看的工作区。
单击 Logs标签页打开交互式日志查看器。
单击 Export 打开原始导出对话框。
从 Service 下拉菜单中选择 Agent 或 Tool。
从 Time period 下拉菜单中，选择前 6、12 或 24 小时的预设范围，或指定自定义范围。自定义范围不能超过 24 小时。然后，从 Time zone 下拉菜单中选择您所在的时区域。
单击 Export下载日志文件。

使用CLI

使用以下CLI命令导出原始运行时日志：

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

以下标志可用：

标记	说明
`--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

以下命令将六个小时的工具服务日志导出到指定文件：

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 Pod 名称
`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 为每个部署记录结构化事件日志，捕获从创建到完成的每个状态转换。您可以使用部署事件日志来跟踪部署行为、调查故障并验证是否发生了预期的生命周期转换。您可以使用平台用户界面、 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`。

使用用户界面

平台用户界面在“部署”页面上显示所有部署（包括活动部署和已完成部署）的“事件日志”标签页。

对于活动部署（即 pending、in_progress 或 cleaning_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。

检查工作区运行状况

部署成功后，您可以随时检查已部署代理的实时运行状况。工作区运行状况视图显示每个代理组件的当前就绪情况、就绪副本数量以及指示上次检查运行状况的时间的时间戳。

使用用户界面

平台用户界面中的工作区概述页面包含“实时部署健康状况”卡。该卡片显示每个组件的运行状况，包括状态、就绪副本和原因。您可以随时单击“刷新”重新获取当前运行状况。上次检查时间时间戳显示上次检索运行状况的时间。

使用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 页面包含 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文档。