1. 에이전트 답이 늦을 때 어디부터 봐야 할까요
Google은 2026년 9월 30일 Gemini Enterprise Agent Platform 릴리스 노트에서 Agent Gateway와 Cloud Trace의 연동을 프리뷰(Preview)로 공개했습니다. 릴리스 노트는 이 연동이 에이전트 워크로드의 요청을 처음부터 끝까지 관측할 수 있게 해 준다고 설명합니다. 같은 날 에이전트 구성도를 제공하는 App Topology API는 정식 제공(GA)이 됐습니다.
에이전트가 도구 여러 개와 MCP 서버, 다른 에이전트를 차례로 부르는 구조에서는 사용자가 답이 늦다고 말해도 어느 호출이 늦었는지 알기 어렵죠. 서비스마다 로그를 따로 열어 시간을 맞춰 봐야 하기 때문입니다. Monitor Agent Gateway 문서는 이 연동으로 서비스 경계를 넘는 요청의 전체 경로를 추적해 지연 병목과 실패한 백엔드 호출을 찾아낼 수 있다고 설명합니다.
2. 프리뷰와 정식 제공을 나눠서 보세요
릴리스 노트는 Cloud Trace를 켜면 요청이 에이전트에서 게이트웨이를 거쳐 Google Cloud 서비스, 도구, 에이전트, MCP 서버로 이동하는 경로를 볼 수 있다고 적고 있습니다("how requests travel from your agents through the gateway and across Google Cloud services, tools, agents, and MCP servers"). 이 기능은 프리뷰 단계이고, 설정에 쓰는 gcloud 명령도 beta 명령입니다.
App Topology API는 GA로 바뀌었습니다. 릴리스 노트에 따르면 사용자 지정 쿼리로 에이전트와 관련된 ID, 알림, 취약점, 기반 인프라 데이터를 더 살펴볼 수 있습니다.
제 판단으로는 운영 대시보드나 장애 대응 절차에 먼저 넣을 수 있는 쪽은 GA인 App Topology API이고, Cloud Trace 연동은 시험 프로젝트에서 먼저 확인해볼 대상입니다. 프리뷰 기능은 정식 제공 전에 동작이나 조건이 바뀔 수 있기 때문입니다. 프리뷰가 언제 끝나는지는 공식 문서에 적혀 있지 않아 확인하지 못했습니다.
| 항목 | 제공 상태 | 공식 문서에서 확인한 내용 |
|---|---|---|
| Agent Gateway Cloud Trace 연동 | Preview | 에이전트에서 게이트웨이를 거쳐 서비스·도구·에이전트·MCP 서버로 가는 요청 경로 관측 |
| App Topology API | GA | 에이전트 구성도 제공, 사용자 지정 쿼리로 ID·알림·취약점·인프라 데이터 조회 |
| Cloud Trace 수집 비용 | 확인하지 못함 | 문서는 샘플링 비율로 수집 비용을 조절하라고 권하지만 단가는 적혀 있지 않음 |
| 한국 리전 지원 | 확인하지 못함 | 공식 문서에 적혀 있지 않음 |
3. 스팬으로 요청 하나를 나눠 읽기
Cloud Trace는 요청 하나를 여러 구간으로 나눠 기록하는데, 이 구간을 스팬(span)이라고 부릅니다. 바깥 요청이 부모 스팬이 되고, 그 안에서 일어난 호출이 자식 스팬이 됩니다. 막대 길이를 비교하면 어느 호출이 오래 걸렸는지 바로 보입니다.
공식 문서에 따르면 호출한 에이전트나 클라이언트 워크로드가 트레이스를 시작해 부모 스팬을 직접 보내는 구조라면, 그 워크로드의 서비스 계정에도 roles/cloudtrace.agent 역할이 있어야 합니다. 이 역할이 없으면 Agent Gateway의 자식 스팬만 기록되고 부모 스팬은 Trace에서 빠집니다("only the Agent Gateway child span is written and the parent span will be missing in Trace"). 그러면 게이트웨이 구간은 보이지만 그 요청이 어느 에이전트 작업에서 시작됐는지 이어서 볼 수 없습니다.
문서는 trace_id로 트레이스 스팬을 게이트웨이 요청 로그와 지표에 연결해 운영 문제를 더 빨리 해결하라고 안내합니다. 트레이스에서 느린 호출을 찾고, 같은 trace_id로 그 시점의 로그를 여는 순서로 쓰면 됩니다(작성자 해석).
4. 샘플링 비율과 권한부터 준비합니다
공식 문서에 따르면 관측 정책 YAML 파일에 samplingRate와 parentBasedSampling 값을 적고, gcloud beta network-services telemetry-policies import 명령으로 정책을 가져온 다음 Trace 탐색기(Trace explorer)에서 결과를 확인합니다.
샘플링 비율은 요청 가운데 얼마를 기록할지 정하는 값입니다. 문서는 트래픽이 많은 운영 환경에서 관측성과 수집 비용의 균형을 맞추려면 1%(0.01) 또는 0.1%(0.001)를 권장합니다. 그런데 비율을 낮추면 드물게 생기는 실패는 기록에 잡히지 않을 수 있습니다. 문서의 문제 해결 절도 트래픽이나 비율이 낮아 트레이스가 바로 보이지 않으면 잠시 100%(samplingRate: 1.00)로 올려 동작을 확인하고, 시험이 끝나면 운영 비율로 되돌리라고 안내합니다. 시험 프로젝트에서는 높은 비율로 경로를 확인하고, 운영으로 옮길 때 권장 범위로 낮추면 됩니다.
권한도 함께 준비해야 합니다. 문서에 따르면 정책을 만들고 고치는 사람에게는 Compute Network Admin 또는 Compute Admin 역할이, 콘솔에서 트레이스를 보는 사람에게는 Cloud Trace User 역할이 필요합니다. 게이트웨이가 스팬을 기록하려면 roles/cloudtrace.agent 역할을 서비스 에이전트 3개에 부여하고, 트레이스를 시작하는 에이전트 워크로드가 있다면 그 서비스 계정에도 부여해야 합니다. 서비스 에이전트 이름과 부여 방법은 문서 원문을 그대로 따르세요.
5. 이번 주에 해볼 일
에이전트가 부르는 도구와 MCP 서버, 다른 에이전트를 한 장에 적어보세요. 호출마다 담당 팀과 지금 로그를 어디서 보는지를 옆에 씁니다.
그다음 시험 프로젝트 하나에서 Cloud Trace 연동을 켜고, 요청 한 건이 이 목록대로 스팬에 나타나는지, 부모 스팬이 빠지지 않는지 확인하면 됩니다. 목록에는 있는데 트레이스에 보이지 않는 호출이 있다면 그 호출의 설정부터 점검하세요.