이 페이지를 사용하여 Agent Gateway 배포를 통해 라우팅되는 트래픽의 로그를 보고, 요청을 모니터링하고, 분산 trace를 추적하는 방법을 알아보세요.
Cloud Logging
Agent Gateway 로그는 networkservices.googleapis.com/Gateway 모니터링 리소스를 사용하여 생성됩니다.
이러한 로그를 사용하여 게이트웨이에 대한 액세스 요청을 모니터링할 수 있습니다. 여기에는 Agent Gateway가 테스트 실행 모드로 배포될 때 생성되는 로그가 포함됩니다. IAP(Identity-Aware Proxy) 통합 액세스 정책(UAP), 시맨틱 거버넌스 정책, Model Armor, VPC 서비스 제어 전반에서 드라이 런 위반 로그를 쿼리하고 통합된 '차단되었을 수 있음' 보고서를 생성하려면 제어 전반에서 드라이 런 정책 위반 감사를 참조하세요.
특정 게이트웨이의 로그 보기
특정 게이트웨이의 로그를 보려면 다음 단계를 완료합니다.
콘솔 쿼리
Google Cloud 콘솔에서 로그 탐색기 페이지로 이동합니다.
쿼리 표시 전환 버튼을 클릭합니다.
다음을 쿼리 필드에 붙여넣습니다.
resource.type="networkservices.googleapis.com/Gateway" resource.labels.location="REGION" resource.labels.gateway_name="AGENT_GATEWAY_NAME"
다음을 바꿉니다.
REGION: 게이트웨이의 리전입니다.AGENT_GATEWAY_NAME: 게이트웨이의 이름입니다.
쿼리 실행을 클릭합니다.
Agent Platform 로그 이름
로그 탐색기에서 특정 유형의 로그 항목을 쿼리하려면 logName 필드를 사용하여 로그 이름으로 쿼리를 필터링하면 됩니다. 다음 표에서는 Agent Gateway 및 에이전트 측 작업에서 생성되는 기본 로그 이름을 설명합니다.
| 로그 이름 | 설명 |
|---|---|
projects/PROJECT_ID/logs/networkservices.googleapis.com%2Fgateway_requests |
게이트웨이 허용 및 거부 결정에 대한 로그입니다. |
projects/PROJECT_ID/logs/cloudaudit.googleapis.com%2Fdata_access |
IAP AuthorizeUser 결정에 대한 Cloud 감사 로그 |
projects/PROJECT_ID/logs/aiplatform.googleapis.com%2Freasoning_engine_stderr |
에이전트 측 시작 및 실행 오류(추론 엔진 stderr) |
projects/PROJECT_ID/logs/aiplatform.googleapis.com%2Freasoning_engine_stdout |
에이전트 측 표준 출력(추론 엔진 stdout) |
PROJECT_ID를 Google Cloud 프로젝트 ID로 바꿉니다.
콘텐츠 정리에 Model Armor를 사용하는 경우 해당 로그는 별도로 내보내집니다. Model Armor 로그를 쿼리하는 방법은 로그 탐색기에서 원시 콘텐츠 보안 로그 보기를 참조하세요.
로깅되는 내용
Agent Gateway 로그 항목에는 게이트웨이로 들어오고 나가는 트래픽을 모니터링하고 디버깅하는 데 유용한 정보가 포함되어 있습니다.
| 필드 | 필드 형식 | 필드 유형: 필수 또는 선택적 | 설명 |
|---|---|---|---|
| severity insertID timestamp receiveTimestamp trace traceSampled logName |
LogEntry | 필수 | 로그 항목에 설명된 일반 필드입니다. |
| httpRequest | HttpRequest | 필수 | HTTP 요청을 로깅하는 데 사용되는 공통 프로토콜입니다. |
| 리소스 | MonitoredResource | 필수 |
|
| jsonPayload | object(Struct format) | 필수 | JSON 객체로 표현되는 로그 항목 페이로드입니다. JSON 객체에는 다음 Agent Gateway 필드가 포함되어 있습니다.
|
정책 전파 및 로그 수집 지연 시간
게이트웨이 액세스 규칙을 업데이트하거나 보안 관련 활동을 조사할 때는 다음 전파 및 수집 기간을 고려하세요.
- 통합 액세스 정책(UAP) 전파: Agent Gateway에서 시행하는 UAP 업데이트(예:
DENY규칙 추가 또는iamEnforcementMode를"DRY_RUN"에서"ENFORCE"로 전환)는 eventual consistency를 갖습니다. 직접 정책 변경사항은 일반적으로 2분 이내에 적용되지만 전역적으로 전파되는 데 7분 이상 걸릴 수 있습니다(액세스 변경 전파 참조).principalSet의 멤버십 변경사항이 동기화되는 데 몇 분에서 몇 시간이 걸릴 수 있습니다. - 긴급 트래픽 중지: UAP 규칙은 Agent Gateway에서 새로운 승인 검사 시 평가되며 에이전트 컨테이너를 종료하거나 이미 설정된 스트리밍 연결을 강제로 닫지 않습니다. 활성 사고 중에 침해되거나 오작동하는 에이전트를 즉시 중지하려면 게이트웨이 거부 규칙을 적용하는 것 외에도 에이전트 런타임을 삭제하거나 버전 트래픽을 다시 라우팅합니다. 자세한 내용은 긴급 중지 및 액세스 취소를 참조하세요.
- 로그, trace, 발견 항목 지연 시간: Agent Gateway는 요청 경로에서 IAP 및 Model Armor 정책을 동기식으로 평가하고 거의 실시간으로
networkservices.googleapis.com/gateway_requests및cloudaudit.googleapis.com/data_access(AuthorizeUser) 로그 항목을 작성합니다(일반적으로 몇 초 이내에 로그 탐색기에서 검색 가능). Trace로 내보낸 분산 trace 스팬도 스팬 완료 후 몇 초 이내에 표시되는 반면, 에이전트 이상 감지의 대역 외 위협 감지는 비동기식으로 평가됩니다(원격 분석 및 보안 발견 항목 지연 시간 참조).
게이트웨이 감사 로그를 보관하고 SIEM으로 내보내기
Agent Gateway 액세스 결정을 변조 방지 규정 준수 증거로 보존하고 위협 모니터링을 중앙 집중화하려면 Logging 버킷을 잠그고 게이트웨이 로그를 보안 정보 및 이벤트 관리(SIEM) 플랫폼으로 스트리밍하면 됩니다.
- 조작 방지 보관(잠긴 로그 버킷):
networkservices.googleapis.com/gateway_requests및cloudaudit.googleapis.com/data_access로그를 구성된 보관 기간(--retention-days)이 있는 커스텀 Logging 버킷으로 라우팅하고 버킷을 영구적으로 잠가(gcloud logging buckets update BUCKET_ID --location=LOCATION --locked) WORM(Write Once Read Many) 규정 준수 스토리지를 적용합니다. 단계별 안내는 감사 로그의 조작 방지 보관을 참조하세요. - SIEM 내보내기:
logName:("networkservices.googleapis.com%2Fgateway_requests" OR "cloudaudit.googleapis.com%2Fdata_access")에 대한 포함 필터를 사용하여 Logging 싱크(또는 조직 수준 집계 싱크)를 만들어 게이트웨이 허용 및 거부 결정을 Google Security Operations(Google SecOps), Pub/Sub(서드 파티 SIEM 수집용), BigQuery 또는 Cloud Storage로 지속적으로 내보냅니다. gcloud CLI 싱크 생성 명령어 및 필터 예시는 SIEM으로 감사 로그 내보내기를 참조하세요.
Cloud Monitoring
Agent Gateway는 일부 Service Extensions 측정항목을 Monitoring으로 내보냅니다. Service Extensions에 승인을 위임하는 경우 이러한 측정항목을 사용하여 확장 프로그램으로 들어오고 나가는 트래픽을 모니터링할 수 있습니다. 자세한 내용은 Cloud Load Balancing 콜아웃의 로깅 및 모니터링을 참조하세요.
모니터링 가능성 대시보드
Agent Gateway는 게이트웨이를 통해 라우팅되는 트래픽을 모니터링, 감사, 디버깅할 수 있는 모니터링 가능성 대시보드를 제공합니다.
- 스코어카드: 승인 시도, 승인 실패, 초당 요청의 총 횟수를 추적합니다.
- 차트: 시간 경과에 따른 승인 실패율(%)과 초당 요청 수를 시각화합니다.
- 이그레스 트래픽 로그:
403거부, 미등록 엔드포인트로의 트래픽, 전반적인 트래픽 추세를 포함한 이그레스 쿼리에 대한 자세한 로그를 검토합니다.
다음 단계를 수행하여 Google Cloud 콘솔에서 게이트웨이의 모니터링 가능성 대시보드에 액세스합니다.
Google Cloud 콘솔에서 Agent Gateway 페이지로 이동합니다.
모니터링할 게이트웨이의 이름을 클릭합니다.
모니터링 가능성 탭을 클릭합니다.
대시보드 데이터 요구사항
Agent Gateway 모니터링 가능성 대시보드는 Observability Analytics를 사용하여 데이터를 표시합니다. 대시보드에서 데이터를 로드하지 않는 경우 Observability Analytics를 사용하도록 _Default 로그 버킷을 업그레이드해야 합니다. 대시보드는 _Default 버킷의 _AllLogs 뷰에서 데이터를 검색합니다.
Cloud Trace 사용
Agent Gateway는 Cloud Trace와 통합되어 에이전트 워크로드에 대한 엔드 투 엔드 요청 모니터링 가능성을 제공합니다. Agent Gateway는 AI 에이전트의 중앙 제어 지점 역할을 하므로 Trace를 사용 설정하면 요청이 에이전트에서 게이트웨이를 통해 여러 Google Cloud 서비스, 도구, 에이전트, MCP 서버로 이동하는 방식을 파악할 수 있습니다. Trace는 이러한 서비스 경계 전반에서 요청 흐름을 추적하여 에이전트 아키텍처에 대한 완전한 분산 추적을 제공합니다.
Trace를 사용하면 다음을 수행할 수 있습니다.
- 정확한 에이전트 상호작용 디버깅: 서비스 경계를 넘나드는 요청의 전체 여정을 추적하여 지연 시간 병목 현상과 실패한 백엔드 호출을 격리합니다.
- 업스트림 샘플링 결정 준수: 업스트림 에이전트 또는 클라이언트가 추적을 시작할 때 상위 기반 샘플링을 사용하여 엔드 투 엔드 추적 연속성을 유지합니다. 이렇게 하면 일상적인 트래픽의 기준 샘플링 레이트를 늘리지 않고도 우선순위가 높은 요청을 완전히 캡처할 수 있습니다.
- 개방형 표준으로 모니터링 가능성 통합: OpenTelemetry 및 W3C TraceContext 표준을 기반으로 빌드된 트레이스는 AI 에이전트, Agent Gateway, 대상 MCP 서버 또는 도구, 서드 파티 모니터링 플랫폼 전반에서 컨텍스트를 원활하게 전파합니다.
- 근본 원인 분석 가속화:
trace_id를 사용하여 trace 스팬을 게이트웨이 요청 로그 및 측정항목과 직접 연결하여 프로덕션 문제를 더 빠르게 해결합니다.
Trace에 대한 자세한 내용은 Cloud Trace 개요를 참조하세요.
필요한 역할
프로젝트에 다음 Identity and Access Management(IAM) 역할이 있어야 합니다.
- 추적 정책 구성 및 업데이트: Compute 네트워크 관리자(
roles/compute.networkAdmin) 또는 Compute 관리자(roles/compute.admin) - Google Cloud 콘솔에서 trace 보기: Cloud Trace 사용자(
roles/cloudtrace.user)
또한 Agent Gateway가 Trace에 trace 스팬을 작성할 수 있도록 하려면 다음 서비스 계정에 Cloud Trace 에이전트 역할(roles/cloudtrace.agent)을 부여해야 합니다.
- Compute Engine 서비스 에이전트:
service-PROJECT_NUMBER@compute-system.iam.gserviceaccount.com - 네트워크 보안 서비스 에이전트:
service-PROJECT_NUMBER@gcp-sa-networksecurity.iam.gserviceaccount.com - Agent Gateway 서비스 에이전트:
service-PROJECT_NUMBER@gcp-sa-agentgateway.iam.gserviceaccount.com - 에이전트 또는 클라이언트 워크로드 서비스 계정: 호출하는 AI 에이전트 또는 클라이언트 워크로드가 trace를 시작하고 자체 상위 스팬을 Trace로 내보내는 경우 워크로드의 서비스 계정 또는 에이전트에 연결된 커스텀 서비스 계정에도 프로젝트에 대한
roles/cloudtrace.agent역할이 부여되어야 합니다. 그렇지 않으면 Agent Gateway 하위 스팬만 작성되고 상위 스팬은 Trace에서 누락됩니다.
PROJECT_NUMBER를 Google Cloud 프로젝트 번호로 바꿉니다.
역할 부여에 대한 상세 설명은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.
추적 사용 설정
Agent Gateway에 대해 추적을 사용 설정하려면 모니터링 가능성 정책 YAML 파일을 만들고 gcloud CLI를 사용하여 가져옵니다.
tracing-policy.yaml이라는 구성 파일을 만듭니다.name: "projects/PROJECT_ID/locations/REGION/telemetryPolicies/POLICY_NAME" telemetryTarget: resources: # You can attach a policy to multiple gateways - "//networkservices.googleapis.com/projects/PROJECT_ID/locations/REGION/agentGateways/AGENT_GATEWAY_NAME" displayName: "Tracing policy for Agent Gateway traffic" tracingConfiguration: samplingRate: SAMPLING_RATE parentBasedSampling: enabled: ENABLE_PARENT_BASED_SAMPLING samplingRate: PARENT_BASED_SAMPLING_RATE다음을 바꿉니다.
PROJECT_ID: Google Cloud 프로젝트 ID입니다.REGION: 게이트웨이의 리전(예:europe-west1)POLICY_NAME: 모니터링 가능성 정책의 이름입니다(예:my-agw-tracing-policy).AGENT_GATEWAY_NAME: 게이트웨이의 이름입니다.SAMPLING_RATE: 추적할 요청의 비율입니다.0.0에서1.0사이의 값으로 설정합니다. 트래픽이 많은 프로덕션 환경의 경우 모니터링 가능성과 수집 비용의 균형을 맞추기 위해 1% (0.01) 또는 0.1% (0.001)의 비율을 사용하는 것이 좋습니다.ENABLE_PARENT_BASED_SAMPLING: 업스트림 호출자로부터 수신되는traceparent헤더의 샘플링된 비트를 적용할지 여부를 제어합니다.true또는false로 설정합니다.PARENT_BASED_SAMPLING_RATE: 추적할 사전 샘플링된 요청의 비율입니다.0.0에서1.0사이의 값으로 설정합니다. 예를 들어1.0는 사전 샘플링된 요청의 100% 를 추적합니다.
모니터링 가능성 정책을 가져옵니다.
gcloud beta network-services telemetry-policies import POLICY_NAME \ --source=tracing-policy.yaml \ --location=REGION
trace 보기
분산 추적을 사용 설정하고 게이트웨이를 통해 트래픽을 전송한 후 Google Cloud 콘솔에서 추적 세부정보를 볼 수 있습니다.
-
Google Cloud 콘솔에서
Trace 탐색기 페이지로 이동합니다.검색창을 사용하여 이 페이지를 찾을 수도 있습니다.
필터 표시줄에 trace 필터 표현식을 입력하거나(예: 지연 시간 기준점, HTTP 상태 코드 또는 요청 URI로 필터링) 특정 trace ID로 검색합니다.
Trace 탐색기 UI 사용에 대한 자세한 내용은 trace 찾기 및 탐색을 참조하세요.
Trace 탐색기
Trace의 Trace 탐색기 뷰 trace 타임라인 뷰
Trace의 타임라인 뷰 trace 그래프 뷰
Trace의 그래프 뷰
trace와 로그 및 측정항목의 상관관계 파악
Agent Gateway는 trace, 로그, 측정항목 간의 원활한 상관관계를 제공합니다.
로그-trace 상관관계: Logging에 기록된 모든 게이트웨이 요청 로그 항목에는
projects/PROJECT_ID/traces/TRACE_ID형식의trace필드가 포함됩니다.- 로그 탐색기에서 로그 항목을 클릭한 후 trace 세부정보 보기를 선택하여 Trace의 해당 스팬으로 직접 이동합니다.
- Trace의 Trace 세부정보 창에서 로그 표시를 클릭하여 해당 요청과 연결된 모든 게이트웨이 요청 로그를 확인합니다.
측정항목 상관관계:
networkservices.googleapis.com/agentgateway/total_latencies와 같은 Monitoring 측정항목에서 관찰된 지연 시간 급증을 trace 스팬 분석과 비교하여 지연 시간 급증이 게이트웨이 내에서 발생했는지 아니면 대상 도구 또는 서버에서 발생했는지 확인합니다.
문제 해결
이 섹션에서는 일반적인 문제와 해결 방법을 설명합니다.
Cloud Trace에 trace가 표시되지 않음:
프로젝트에 Cloud Trace API(
cloudtrace.googleapis.com)가 사용 설정되어 있는지 확인합니다.gcloud services enable cloudtrace.googleapis.com --project=PROJECT_ID
필수 Cloud Trace 에이전트 IAM 역할(
roles/cloudtrace.agent)이 모든 필수 서비스 계정에 부여되었는지 확인합니다.모니터링 가능성 정책이 올바른 리전에 있고 적절한 Agent Gateway 게이트웨이를 참조하는지 확인합니다.
gcloud beta network-services telemetry-policies describe POLICY_NAME \ --location=REGION구성된
samplingRate를 확인합니다. 트래픽 양이 적거나 샘플링 레이트가 낮으면 trace가 즉시 캡처되지 않을 수 있습니다. 추적이 작동하는지 확인하려면 정책을 일시적으로 업데이트하여 100% 샘플링(samplingRate: 1.00)을 사용하면 됩니다. 테스트가 완료되면 프로덕션 비율을 복원합니다.
불완전한 trace 스팬:
trace 스팬이 애플리케이션 요청의 하위 스팬이 아닌 독립적이거나 연결이 끊긴 루트 trace로 표시되는 경우 다음을 수행합니다.
- 모니터링 가능성 정책에서
parentBasedSampling가 사용 설정(true로 설정)되어 있는지 확인합니다. - 상위 스팬을 Trace로 내보낼 수 있도록 호출하는 AI 에이전트 또는 워크로드의 서비스 계정에 프로젝트에 대한 Cloud Trace 에이전트 역할(
roles/cloudtrace.agent)이 부여되었는지 확인합니다. - W3C
traceparent헤더가 서비스 경계를 넘어 전파되도록 애플리케이션이 분산 trace 컨텍스트 전파가 사용 설정된 OpenTelemetry SDK를 사용하는지 확인합니다. 자세한 내용은 OpenTelemetry TraceContext 전파자 문서를 참조하세요.
- 모니터링 가능성 정책에서
다음 단계
Codelab: Agent Platform으로 에이전트 워크로드 관리
Gemini Enterprise Agent Platform에서 Agent Gateway를 사용하여 에이전트형 워크로드를 제어하는 방법을 알아봅니다.