에이전트 모니터링

개요

이 가이드 에서는 에이전트의 성능과 배포 상태를 모니터 하는 방법을 학습 수 있습니다.

에이전트 샌드박스는 실행 중에 에이전트 동작을 모니터 하고 문제를 진단하는 데 사용할 수 있는 로그를 생성합니다. 이러한 로그는 다음과 같은 방법으로 조회 할 수 있습니다.

API 또는 CLI 에이전트 로그 사용: stdout/stderr 출력, print() 문 및 프레임워크 디버그 출력을 포함한 에이전트 런타임 로그를 조회합니다.
배포서버 이벤트 로그에 API 사용: 구조화된 배포서버 이벤트 로그에 액세스하여 배포서버 동작을 추적하고, 실패를 조사하고, 수명 주기 전환을 확인합니다.

배포된 에이전트 의 실시간 상태를 확인하려면 플랫폼 UI 에서 agentengine status 명령 또는 작업 공간 상태 카드를 사용합니다.

특정 에이전트 실행 시 지연 시간 또는 예기치 않은 동작을 디버깅하려면 에이전트 실행 추적 검사를 참조하세요.

에이전트 런타임 로그 보기

MongoDB Atlas Agent Engine은 배포된 에이전트에서 stdout/stderr 출력, print() 문, logging 호출 및 프레임워크 디버그 출력을 캡처하여 S3에 저장합니다. 플랫폼 UI, API 또는 CLI 사용하여 이러한 로그를 조회 할 수 있습니다.

UI 사용

UI 에서 로그를 보려면 다음 단계를 수행하세요.

왼쪽 탐색 모음에서 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 시작 시간입니다. 기본값은 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 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 또는 regex가 아닙니다.
`--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 Lines 파일 로 다운로드 할 수 있습니다.

UI 사용

UI 에서 원시 런타임 로그를 내보내려면 다음 단계를 수행하세요.

왼쪽 탐색 모음에서 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

다음 명령은 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 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은 각 배포서버 에 대한 구조화된 이벤트 로그 기록하여 생성부터 완료까지의 모든 상태 전환을 캡처합니다. 배포 이벤트 로그 사용하여 배포서버 동작을 추적하고, 실패를 조사하고, 예상되는 수명 주기 전환이 발생했는지 확인할 수 있습니다. 플랫폼 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_progress 또는 cleaning_up인 활성 배포의 경우 이벤트는 SSE를 통해 실시간 스트림 .
완료된 배포의 경우 카드는 REST 엔드포인트에서 전체 이벤트 기록을 로드합니다.

각 이벤트 행에는 UTC 타임스탬프, 심각도 수준(info, success, warn 또는 error), 수명 주기 단계, 구성 요소 및 메시지가 표시됩니다. 이벤트를 레벨 및 단계별로 필터하다 보기 범위를 좁힐 수 있습니다.

CLI 사용

특정 배포서버 에 대한 이벤트 로그 보려면 agentengine deploy logs 명령을 사용합니다. 자세한 학습 은 배포 이벤트 로그 보기를 참조하세요.

agentengine deploy get와 함께 -f 플래그를 사용하여 활성 배포서버 중에 이벤트를 실시간 스트림 할 수도 있습니다. 자세히 학습 배포 상태 확인을 참조하세요.

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 으로 출력합니다.

정책 거부 보기

플랫폼 UI 의 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 설명서를 참조하세요.

돌아가기

Atlas 역할 권한

에이전트 실행 추적 검사