28. 평가(4)- 중앙집중형 관측 체계(Observability)

 

이번에는 앞서 실습한 Python logging을 한 단계 발전시켜, 여러 Agent와 Tool의 실행 정보를 Google Cloud에 모아 관찰하는 중앙집중형 관측(Observability) 체계를 구축해 보겠습니다.

 

이번 실습의 핵심은 단순히 로그 파일을 만드는 것이 아닙니다.예를 들어 앞으로 사용자가 Manager Agent에 질문하면 Manager Agent가 Weather Agent를 호출하고, Weather Agent가 날씨 Tool을 실행한다고 생각해 보겠습니다. 이때 각 구성요소의 실행 흐름과 소요 시간, 오류, 호출 관계를 한곳에서 확인할 수 있도록 만드는 것입니다.

 

사용하시는 환경을 기준으로 설명하겠습니다.

항목	실습 환경
OS	Windows / PowerShell
프로젝트 경로	C:\Dev\book_agentic_ai\adk_
GCP 프로젝트	agent-project-512212
GCP 프로젝트 번호	921865052026
리전	asia-northeast3
ADK	기존 실습 환경의 google-adk 2.13.0
실행 방식	ADK Web 또는 ADK CLI
관측 대상	OpenTelemetry 기반 Agent 실행 정보

먼저 중요한 개념부터 짚겠습니다.

1. OpenTelemetry란 무엇인가?

OpenTelemetry(OTel)는 애플리케이션의 실행 상태를 관찰하기 위한 개방형 표준 기술입니다.

특정 클라우드 업체에 종속되지 않고, 다양한 프로그래밍 언어와 프레임워크에서 관측 데이터를 생성하고 전달할 수 있도록 표준화한 기술입니다. 일반적으로 다음 세 가지 데이터를 다룹니다. 

이 세 가지를 함께 보면 단순한 오류 확인을 넘어 Agent 시스템 전체의 상태를 분석할 수 있습니다.

2. 이번 실습의 전체 구조

이번에 사용하려는 --otel_to_cloud는 ADK에서 OpenTelemetry 관측 데이터를 Google Cloud로 내보내는 기능입니다.

전체 구조는 다음과 같습니다. 

여기서 한 가지 구분해야 합니다.

• OpenTelemetry는 관측 데이터를 생성하고 전달하는 표준입니다.

• Google Cloud Observability는 전달받은 데이터를 저장하고 검색하고 시각화하는 서비스입니다.

• --otel_to_cloud는 ADK 실행 시 이 연동을 간편하게 설정하기 위한 옵션입니다.

즉, 이 옵션 하나가 모든 관측 데이터를 동일한 방식으로 생성한다는 뜻은 아닙니다. 실제로 어떤 종류의 데이터가 생성되는지는 ADK 버전, Instrumentation, Agent 실행 방식에 따라 달라집니다.

3. 사전 준비: ADK 버전, GCP 프로젝트, 인증 확인

3-1. ADK 버전 확인

먼저 PowerShell에서 현재 가상환경이 활성화되어 있는지 확인합니다.

(venv) PS C:\Dev\book_agentic_ai\adk_>

다음 명령을 실행합니다.

python -m pip show google-adk

예상되는 핵심 정보는 다음과 같습니다.

Name: google-adk
Version: 2.13.0

Google Cloud 공식 가이드에서는 ADK 1.17.0 이상에 OpenTelemetry 지원이 내장되어 있다고 안내하고 있습니다. 현재 사용 중인 2.13.0은 이 조건을 충족합니다.

 

다음으로 CLI에 옵션이 실제로 있는지 확인합니다.

adk web --help | Select-String otel

--otel_to_cloud가 표시되는지 확인하세요.

3-2. Google Cloud 프로젝트 확인

이번 실습에서는 기존에 사용하던 프로젝트를 그대로 사용하겠습니다.

Project ID     : agent-project-512212
Project Number : 921865052026
Region         : asia-northeast3

PowerShell에서 다음을 실행합니다.

gcloud config set project agent-project-512212

현재 프로젝트 확인:

gcloud config get-value project

결과:

agent-project-512212

프로젝트 번호도 확인할 수 있습니다.

gcloud projects describe agent-project-512212

3-3. Google Cloud 인증 확인

이전에 사용했던 Application Default Credentials(ADC) 방식을 그대로 이용하겠습니다.

gcloud auth login

브라우저에서 Google 계정 인증을 완료합니다.

그다음 애플리케이션에서 사용할 ADC 인증을 설정합니다.

gcloud auth application-default login

마지막으로 Vertex AI API의 할당량 프로젝트도 지정합니다.

gcloud auth application-default set-quota-project agent-project-512212

여기서 두 인증을 구분하면 좋습니다.

명령	역할
gcloud auth login	gcloud CLI 명령 실행을 위한 인증
gcloud auth application-default login	Python 애플리케이션이 Google Cloud API를 호출할 때 사용하는 ADC 인증

특히 이번 OpenTelemetry 내보내기는 Python 애플리케이션이 Google Cloud에 관측 데이터를 전송하는 작업이므로 ADC 인증이 중요합니다.

3-4. Google Cloud API 활성화

이번 실습에서는 다음 API를 사용합니다.

API	용도
Vertex AI API	Gemini 모델 호출
Service Usage API	API 사용 관리
Telemetry API	OpenTelemetry 데이터 수신
Cloud Logging API	로그 저장
Cloud Monitoring API	메트릭 저장 및 조회
Cloud Trace API	분산 추적 데이터 저장 및 조회

PowerShell에서 한 번에 활성화합니다.

gcloud services enable `
    aiplatform.googleapis.com `
    serviceusage.googleapis.com `
    telemetry.googleapis.com `
    logging.googleapis.com `
    monitoring.googleapis.com `
    cloudtrace.googleapis.com

이 명령은 프로젝트에서 필요한 API를 활성화합니다. 이미 활성화된 API는 그대로 유지됩니다.

 

활성화 여부를 확인합니다.

gcloud services list --enabled

목록에서 위 API 이름들을 확인하면 됩니다.

3-5. IAM 권한 확인

이 부분은 매우 중요합니다.

API가 활성화되어 있더라도 Python 애플리케이션을 실행하는 Google 계정에 쓰기 권한이 없다면 Cloud로 데이터를 전송할 수 없습니다.

Google Cloud 공식 가이드가 안내하는 권한은 다음과 같습니다.

IAM 역할	역할 ID	목적
Cloud Telemetry Traces Writer	roles/telemetry.tracesWriter	Trace 전송
Logs Writer	roles/logging.logWriter	로그 전송
Monitoring Metric Writer	roles/monitoring.metricWriter	메트릭 전송
Vertex AI User	roles/aiplatform.user	Gemini 모델 사용

이 역할들은 GCP 콘솔에서 다음 경로로 확인할 수 있습니다.

1. Google Cloud Console 접속

2. 프로젝트 agent-project-512212 선택

3. IAM 및 관리자 → IAM

4. 현재 인증한 Google 계정 검색

5. 위 역할들이 부여되어 있는지 확인

프로젝트 Owner 권한이 있더라도 별도 사용자나 서비스 계정으로 실행하는 경우에는 그 실행 주체의 권한을 확인해야 합니다.

운영 환경에서는 개인 사용자 계정 대신 서비스 계정에 필요한 권한을 부여하는 방식이 일반적입니다.

4. OpenTelemetry 관련 Python 패키지 설치

이제 Python 환경에 OpenTelemetry 관련 패키지를 설치하겠습니다.

Google Cloud 공식 가이드는 ADK 외에 다음 패키지를 추가하도록 안내합니다.

패키지	역할
opentelemetry-instrumentation-google-genai	Google GenAI 호출 계측
opentelemetry-instrumentation-sqlite3	SQLite 작업 계측
opentelemetry-exporter-otlp-proto-grpc	OTLP gRPC 전송
opentelemetry-exporter-otlp-proto-http	OTLP HTTP 전송
opentelemetry-instrumentation-vertexai	Vertex AI 호출 계측

현재 ADK 2.13.0을 유지하면서 설치하겠습니다.

* 아래와 같이 설치하면 에러가 발생하는 경우, 그 해결에 대해서는 다음을 확인 해주세요...

2026.11.10 - [Agentic AI/Google ADK] - 29. 평가(4.x)- OpenTelemetry 패키지와 Google ADK 사이의 버전 의존성 충돌(Dependency Conflict)

 

python -m pip install `
    "opentelemetry-instrumentation-google-genai>=0.7b1" `
    "opentelemetry-instrumentation-sqlite3>=0.63b1" `
    "opentelemetry-exporter-otlp-proto-grpc>=1.42.1" `
    "opentelemetry-exporter-otlp-proto-http>=1.42.1" `
    "opentelemetry-instrumentation-vertexai>=2.0b0"

여기서 google-adk 자체를 다시 설치하지 않는 이유는 이미 2.13.0을 사용하고 있기 때문입니다.

 

* 위와 같이 설치하면 에러가 발생하는 경우, 그 해결에 대해서는 다음을 확인해주세요...

2026.11.10 - [Agentic AI/Google ADK] - 29. 평가(4.x)- OpenTelemetry 패키지와 Google ADK 사이의 버전 의존성 충돌(Dependency Conflict)

 

설치 후 다음 명령으로 의존성 충돌 여부를 확인합니다.

python -m pip check

정상이라면 다음과 비슷하게 나옵니다.

No broken requirements found.

그리고 주요 패키지가 설치되었는지 확인합니다.

python -m pip list | Select-String "opentelemetry"

주의: 기존 가상환경에는 Vertex AI, ADK, PostgreSQL, Agent Engine 관련 패키지도 설치되어 있으므로 의존성 변경에 주의하세요. pip check에서 충돌이 발생하면 무작정 추가 업그레이드하기보다 충돌 메시지를 먼저 확인하는 것이 좋습니다.

5. OpenTelemetry 환경변수 설정

이번 실습에서 가장 중요한 설정입니다.

OpenTelemetry는 환경변수를 통해 서비스 이름, 데이터 수집 범위, GenAI 메시지 수집 방식 등을 지정할 수 있습니다.

Google 공식 가이드에서 사용하는 주요 환경변수는 다음과 같습니다.

환경변수	설정값	역할
OTEL_SERVICE_NAME	neoleap-weather-adk	관측 대상 서비스 이름
OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED	true	Python logging 계측 활성화
OTEL_SEMCONV_STABILITY_OPT_IN	gen_ai_latest_experimental	최신 GenAI 표준 속성 사용
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT	EVENT_ONLY	메시지 내용을 이벤트에 기록
ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS	false	메시지를 Span 속성에 직접 넣지 않음

5-1. PowerShell에서 환경변수 설정

이번에는 환경변수 파일을 별도로 만들기보다는 PowerShell에서 직접 설정하겠습니다.

현재 PowerShell 창에서 다음 코드를 순서대로 실행하세요.

$env:GOOGLE_CLOUD_PROJECT = "agent-project-512212"
$env:GOOGLE_CLOUD_LOCATION = "asia-northeast3"

$env:OTEL_SERVICE_NAME = "neoleap-weather-adk"

$env:OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED = "true"

$env:OTEL_SEMCONV_STABILITY_OPT_IN = "gen_ai_latest_experimental"

$env:OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT = "EVENT_ONLY"

$env:ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS = "false"

서비스 이름은 임의로 정할 수 있습니다.

이번에는 다음과 같이 지정했습니다.

neoleap-weather-adk

나중에 여러 Agent를 운영할 때는 서비스 이름을 구분하면 좋습니다.

neoleap-manager-agent
neoleap-weather-agent
neoleap-research-agent
neoleap-document-agent

이렇게 해두면 Cloud에서 서비스별 관측 데이터를 구분하는 데 도움이 됩니다.

5-2. 환경변수 설정 확인

다음 명령어를 실행합니다.

$env:OTEL_SERVICE_NAME
$env:OTEL_SEMCONV_STABILITY_OPT_IN
$env:OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT
$env:ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS

예상 결과:

neoleap-weather-adk
gen_ai_latest_experimental
EVENT_ONLY
false

5-3. 메시지 수집 설정을 왜 이렇게 했을까?

여기에는 중요한 보안상의 이유가 있습니다.

OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT는 사용자의 질문과 Agent 응답 내용을 관측 데이터에 포함할지를 결정합니다.

공식 문서에서 안내하는 주요 값은 다음과 같습니다.

값	의미
NO_CONTENT	메시지 내용 수집 안 함
EVENT_ONLY	이벤트에 메시지 내용 포함
SPAN_ONLY	Span에 메시지 내용 포함
SPAN_AND_EVENT	Span과 이벤트 모두에 포함

이번에는 학습 목적으로 EVENT_ONLY를 선택했습니다.

단, 이 설정은 실제 사용자 질문과 Agent 응답을 Cloud에 기록할 수 있습니다. 개인정보, 고객 정보, 계약서 내용 등이 포함될 수 있으므로 실습에서는 가상의 질문만 사용하세요.

또한 최신 GenAI Semantic Convention을 사용할 때는 EVENT_ONLY처럼 명시적인 값을 지정하는 것이 좋습니다. Google Cloud 공식 문서는 이 조합에서 true를 사용하면 잘못된 설정이 되어 로그와 Trace가 수집되지 않을 수 있다고 경고합니다.

 

ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS=false는 메시지 내용을 Span의 일반 속성으로 중복해서 넣지 않도록 하는 설정입니다. 메시지 수집 자체를 완전히 차단하는 설정과는 다릅니다.

6. ADK Web 실행하기: 핵심 명령어

이제 모든 준비가 끝났습니다.

앞서 만든 Weather Agent를 대상으로 테스트하겠습니다.

현재 프로젝트 구조는 다음과 같습니다.

C:\Dev\book_agentic_ai\adk_\
│
├── agent\
│   └── agent.py
│
├── weather_eval_agent\
│   ├── __init__.py
│   └── weather_agent.py
│
├── evals\
│
└── reports\

이번에는 기존 GCS Artifact Agent가 아닌, 앞서 평가용으로 분리했던 weather_eval_agent만 실행하겠습니다.

6-1. ADK Web 실행

PowerShell에서 다음 명령을 실행합니다.

adk web --otel_to_cloud --port 8080 .\weather_eval_agent

이 명령을 구성요소별로 살펴보겠습니다.

명령어	의미
adk web	ADK Web 서버 실행
--otel_to_cloud	OpenTelemetry 데이터를 Google Cloud로 전송
--port 8080	웹 서버 포트 지정
.\weather_eval_agent	실행할 Agent 폴더 지정

공식 ADK 문서에서도 adk web --otel_to_cloud 형태로 GCP 내보내기를 활성화하도록 안내하고 있습니다.

6-2. 정상 실행 확인

PowerShell에 다음과 비슷한 메시지가 표시되면 됩니다.

INFO:     Started server process
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8080

브라우저에서 다음 주소로 접속합니다.

ADK Web UI 열기

화면에서 weather_eval_agent를 선택합니다.

6-3. Agent에게 질문하기

다음과 같은 질문을 순서대로 입력해 보세요.

테스트 1: 정상적인 Tool 호출

서울의 현재 날씨를 알려줘.

테스트 2: 다른 도시

대전의 현재 날씨를 알려줘.

테스트 3: 두 도시 비교

서울과 대전 중 어디가 더 따뜻해?

테스트 4: 오류 상황 확인

부산의 현재 날씨를 알려줘.

각 질문에 대한 응답이 정상적으로 생성되는지 확인합니다.

이 과정에서 ADK 내부에서는 Agent 실행, LLM 호출, Tool 실행 등의 작업이 발생합니다. ADK의 OpenTelemetry 계측은 이런 주요 실행 과정을 Span으로 표현합니다.

7. Google Cloud에서 관측 데이터 확인하기

이제 가장 중요한 단계입니다.

ADK Web에서 질문을 실행하는 것만으로는 중앙집중형 관측체계가 완성되지 않습니다.

실제로 데이터가 Google Cloud에 도착했는지 확인해야 합니다.

Google Cloud Console에서 프로젝트를 agent-project-512212로 선택하세요.

 

확인할 곳은 크게 세 군데입니다.

1. Cloud Trace(우선 확인)

Agent 실행 흐름과 Tool 호출 관계를 확인합니다.

Google Cloud Trace Explorer

 

2. Cloud Logging

Agent 실행 로그, LLM 관련 이벤트, Tool 관련 로그 등을 확인합니다.

Google Cloud Logs Explorer

 

3. Cloud Monitoring

메트릭을 조회하고 시간에 따른 변화와 시스템 상태를 분석합니다.

Google Cloud Metrics Explorer

7-1. Cloud Trace 확인하기

먼저 Cloud Trace Explorer로 이동합니다.

여기서 확인할 것은 Span입니다.

Span이란 하나의 작업이 시작해서 끝날 때까지의 실행 구간을 의미합니다.

예를 들어 다음과 같은 실행이 있었다고 가정하겠습니다.

사용자 질문
    │
    ▼
Weather Agent 실행
    │
    ├── LLM 호출
    │
    └── Tool 실행
          │
          ▼
      get_current_weather
    │
    ▼
최종 응답 생성

실제 Trace에서는 부모 Span과 자식 Span의 관계로 나타납니다.

ADK의 현재 Trace 문서에서 안내하는 대표적인 Span 이름은 다음과 같습니다.

Span 이름	의미
invoke_agent {agent.name}	Agent 실행
invoke_workflow {workflow.name}	Workflow 실행
execute_tool {tool.name}	Tool 실행
generate_content {model.name}	LLM 콘텐츠 생성

실제 Trace Explorer에서 확인할 때는 다음 순서로 진행하세요.

1. Trace Explorer에 접속합니다.

2. 프로젝트가 agent-project-512212인지 확인합니다.

3. 시간 범위를 최근 15분 또는 1시간으로 지정합니다.

4. Span 목록에서 Agent 실행 기록을 찾습니다.

5. 하나의 Trace를 선택합니다.

6. 해당 Trace에 연결된 자식 Span을 확인합니다.

특히 다음을 확인해야 합니다.

• 어떤 Agent가 실행되었는가?

• 어떤 LLM 모델을 호출했는가?

• 어떤 Tool을 실행했는가?

• 각 작업에 걸린 시간은 얼마인가?

• 오류가 발생한 Span은 무엇인가?

참고: Google Cloud의 기존 안내 자료에는 call_llm이라는 Span 이름이 등장하기도 합니다. 현재 ADK 문서의 최신 GenAI Semantic Convention 기반 Span 이름과 다를 수 있으므로, 이름 하나만 고집하지 말고 Agent, Tool, 모델 호출 Span을 함께 확인하세요.

처음 Cloud Trace를 사용하는 프로젝트에서는 Trace 저장소를 초기화하는 데 몇 분이 걸릴 수 있습니다. 따라서 첫 실행 직후 데이터가 안 보인다고 바로 실패로 판단하지는 마세요.

7-2. Cloud Logging 확인하기

이번에는 Logs Explorer로 이동합니다.

여기서는 실행 과정에서 발생한 로그와 이벤트를 확인합니다.

예를 들어 다음과 같은 종류의 정보가 나타날 수 있습니다.

Agent initialized
Session created
LLM request
LLM response
Tool execution
Tool result
Agent response

다만 위 내용은 이해를 돕기 위한 예시이며, 실제 로그 이름과 구조는 ADK 버전 및 로그 설정에 따라 다를 수 있습니다.

특히 이번 실습에서는 EVENT_ONLY를 설정했기 때문에, 메시지 내용이 이벤트에 기록되도록 설정되어 있습니다.

로그 상세 항목을 열어서 다음을 확인하세요.

• 로그가 발생한 시각

• 로그 레벨

• 서비스 이름

• 로그 메시지

• 연결된 Trace 정보

• 이벤트에 포함된 입력과 출력 내용

Google Cloud 공식 가이드에서는 Trace의 상세 화면에서 Logs & Events 탭을 통해 관련 로그를 살펴볼 수 있다고 설명합니다.

7-3. Cloud Monitoring 확인하기

이제 Metrics Explorer로 이동합니다.

여기서는 수치 데이터를 확인합니다.

예를 들어 다음과 같은 항목을 분석할 수 있습니다.

관측 항목	분석 목적
LLM 호출 횟수	모델 호출 빈도
입력 토큰	프롬프트 처리량
출력 토큰	생성된 응답량
LLM 호출 시간	모델 응답 속도
Tool 실행 시간	외부 기능 처리 속도
오류 발생	실행 안정성

여기서 주의할 점은 Metrics Explorer에 위 항목들이 모두 같은 이름으로 자동 표시되는 것은 아니라는 것입니다.

ADK 버전과 계측 라이브러리, 실제 사용한 Agent 기능에 따라 생성되는 메트릭이 달라집니다.

따라서 Metrics Explorer에서 메트릭 선택기를 열고 gen_ai 등 관련 키워드로 검색해 실제 생성된 메트릭을 확인하는 것이 좋습니다.

8. 앞서 작성한 Python logging 코드와 OpenTelemetry는 어떻게 연결될까?

이 부분은 앞선 학습과 연결되는 중요한 개념입니다.

지난번에 사용했던 코드를 기억하실 겁니다.

import logging

logging.basicConfig(
    level=logging.INFO,
    filename="app.log",
    format="%(asctime)s - %(levelname)s - %(name)s - %(message)s",
)

logger = logging.getLogger(__name__)

그리고 함수 안에서 다음처럼 기록했습니다.

logger.info(
    "get_current_weather 호출: location=%s",
    location,
)

여기서 두 기술의 역할을 구분해야 합니다.

구분	Python logging	OpenTelemetry
역할	로그 메시지 생성	관측 데이터 표준화 및 전달
기록 대상	INFO, WARNING, ERROR 등	Logs, Metrics, Traces
출력 위치	파일, 콘솔 등	Cloud 또는 OTLP 호환 백엔드
실행 흐름 추적	기본적으로 어려움	Trace와 Span으로 추적
여러 서비스 통합	별도 구성 필요	표준 Context 전파 활용

이번에 설정한 다음 환경변수를 다시 살펴보겠습니다.

$env:OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED = "true"

이 설정은 Python의 표준 logging을 OpenTelemetry의 로그 계측과 연결하는 데 사용됩니다.

따라서 기존 logger.info() 등의 메시지도 적절히 계측되면 Cloud Logging으로 내보낼 수 있습니다.

다만 기존 logging.basicConfig(filename="app.log")가 설정한 파일 출력이 자동으로 Cloud로 복사된다는 뜻은 아닙니다. OpenTelemetry 로그 Exporter가 연결되어 있고 해당 로거의 로그가 계측 경로를 통과해야 합니다.

즉, 파일 로그와 Cloud 로그는 별개의 출력 경로로 이해하는 것이 좋습니다.

9. 이번 실습에서 발생할 수 있는 오류와 해결 방법

실습 과정에서 문제가 생겼을 때 아래 순서대로 확인하면 됩니다.

증상	확인할 사항	조치
--otel_to_cloud 옵션을 인식하지 못함	ADK 버전과 CLI 경로	pip show google-adk, adk web --help
인증 오류	ADC 인증	gcloud auth application-default login
권한 오류	IAM 역할	Trace Writer, Logs Writer, Metric Writer 확인
API 호출 실패	API 활성화 여부	gcloud services list --enabled
Trace가 안 보임	시간 범위, Trace 저장소	몇 분 기다린 뒤 다시 조회
Logs가 안 보임	Logging 계측 및 Exporter	환경변수와 IAM 확인
Metrics가 안 보임	실제 메트릭 생성 여부	Metrics Explorer에서 메트릭 검색
Agent가 실행되지 않음	기존 ADK 환경 문제	python -m pip check, 실행 로그 확인

특히 다음 세 가지는 꼭 기억하세요.

1. ADK Web이 정상 실행됐다고 해서 Cloud 전송까지 성공했다는 뜻은 아닙니다.

2. Trace가 보인다고 해서 Logs와 Metrics까지 모두 정상이라는 뜻도 아닙니다.

3. Cloud에서 데이터가 안 보일 때는 IAM, API, ADC 인증, 환경변수를 각각 확인해야 합니다.

10. 이번 실습을 성공으로 판단하는 기준

제가 권장하는 실습 완료 기준은 다음과 같습니다.

OpenTelemetry 실습 체크리스트

 

- ADK 버전 2.13.0 및 --otel_to_cloud 옵션 확인

- GCP 프로젝트 agent-project-512212 선택

- ADC 인증 및 quota project 설정

- Telemetry, Logging, Monitoring, Trace API 활성화 확인

- 필요한 IAM 쓰기 권한 확인

- OpenTelemetry 패키지 설치 및 pip check 통과

- PowerShell 환경변수 설정 확인

- ADK Web을 --otel_to_cloud 옵션으로 실행

- Weather Agent 질문 3~4개 실행

- Cloud Trace에서 Agent와 Tool Span 확인

- Cloud Logging에서 실행 로그 확인

- Cloud Monitoring에서 실제 생성된 메트릭 확인

 

11. 한 단계 더: 앞으로 만들 Manager Agent와 연결하기

이번 실습의 가장 큰 가치는 이후 멀티에이전트 시스템을 개발할 때 나타납니다.

지금까지 공부한 구조를 연결해 보겠습니다.

이 구조가 구축되면 다음과 같은 질문에 답할 수 있습니다.

• Manager Agent가 어떤 Agent를 호출했는가?

• Weather Agent는 응답을 생성하는 데 얼마나 걸렸는가?

• Research Agent에서 오류가 발생했는가?

• 특정 Tool이 지나치게 오래 실행되는가?

• 모델별 토큰 사용량은 얼마인가?

• 전체 요청 중 오류가 발생하는 비율은 얼마인가?

이런 수준까지 도달하면 단순한 Agent 개발을 넘어 **Agent 운영 및 관측 체계(Agent Observability)**를 구축하는 단계로 넘어가는 것입니다.

12. 핵심 정리

이번 학습에서 꼭 기억할 것은 다음 다섯 가지입니다.

1. OpenTelemetry는 Logs, Metrics, Traces를 다루는 개방형 표준입니다.

2. Google ADK는 OpenTelemetry 계측을 내장하고 있으며, --otel_to_cloud 옵션으로 Google Cloud 내보내기를 활성화할 수 있습니다.

3. Google Cloud Observability는 데이터를 받아 저장하고 조회하는 플랫폼입니다.

4. Trace는 실행 흐름, Logs는 발생한 사건, Metrics는 수치와 추세를 보여줍니다.

5. 기존 Python logging과 OpenTelemetry를 연결하면 직접 작성한 로그와 ADK 내부 실행 정보를 함께 관찰하는 기반을 만들 수 있습니다.

공식 참고 자료도 함께 남겨두겠습니다.

• Google Cloud: Instrument ADK applications with OpenTelemetry

• ADK: Traces

• ADK: Logging

• ADK: Metrics

권장하는 다음 실습은 Manager Agent → Weather Agent → Tool 구조를 실제로 실행하고, Cloud Trace에서 하나의 사용자 요청이 여러 Agent와 Tool을 거치는 과정을 추적하는 것입니다. 그때 A2A로 연결된 별도 프로세스까지 Trace Context가 이어지는지 확인하면 분산 추적의 의미를 훨씬 깊이 이해할 수 있습니다.