에이전트 관측성
메트릭/트레이스/로그, OpenTelemetry, Golden Signals
에이전트 관측성
메트릭/트레이스/로그, OpenTelemetry, Golden Signals
보이지 않으면 고칠 수 없다
OTel 기반 계측부터 프로덕션 대시보드까지
왜 에이전트 관측성이 필요한가
비결정성 · 동적 경로 · 토큰 비용 · 디버깅 불가
왜 관측성인가
비결정적 시스템을 로그만으로 디버깅할 수 없는 이유의 조감
보이지 않으면 고칠 수 없다
에이전트는 실행 경로가 동적이라 전통 앱의 디버깅 방식이 통하지 않습니다.
- 비결정성 — 같은 입력에 다른 실행 경로
- 비용 요인 — CPU가 아닌 토큰 소비량
- 에러 유형 — 환각 · 무한 루프 · 잘못된 도구 선택
- Trajectory — 스택 트레이스 대신 도구 호출 시퀀스
전통 앱의 스택 트레이스와 CPU 지표로는 에이전트를 진단할 수 없습니다 — 실행 경로와 토큰까지 보이게 만드는 계측이 프로덕션의 전제조건입니다.
전통 앱 vs 에이전트
실행 경로가 동적인 에이전트 — 로그만으로는 불가능한 디버깅
관측성 없이 발생하는 문제
프로덕션에서 무엇이 잘못되었는지 알 수 없는 4가지 상황
"느려졌다"
LLM 지연인지, 도구 지연인지, 루프 반복인지 구분 불가
"비용 폭증"
어떤 세션이 토큰을 많이 썼는지 추적 불가 — IAM Principal 귀속 없으면 사각지대
"이상한 답변"
어떤 도구에서 어떤 데이터를 받았는지 로그 없음 — 환각인지 도구 오류인지 모름
"간헐 에러"
재현 불가능 — 트레이스 없으면 원인 파악 불가, 고객 불만만 쌓임
네 상황의 공통점은 실행 내부가 보이지 않는 것입니다 — 지연·비용·품질·재현 모두 계측이 선행 조건입니다.
관측성 3대 요소
Metrics · Traces · Logs — 세 가지가 결합되어야 완전한 관측성
관측성 3대 요소
메트릭·트레이스·로그 세 축이 각각 답하는 질문의 조감
Metrics · Traces · Logs
세 가지 텔레메트리가 결합되어야 완전한 관측성이 됩니다.
- Metrics — "이상 있나?" 수치 시계열 집계
- Traces — "어디가 문제?" 요청의 전체 경로
- Logs — "왜 발생했나?" 개별 이벤트 상세
- Span 계층 — Agent Loop → Model → Tool → External
메트릭으로 이상을 감지하고, 트레이스로 위치를 좁히고, 로그로 원인을 확인합니다 — 세 축이 결합되어야 완전한 관측성이 됩니다.
3축 텔레메트리
메트릭으로 이상 감지 → 트레이스로 위치 추적 → 로그로 원인 확인
Metrics (지표)
수치 시계열 — 지연, 토큰, 에러율을 집계하여 추이 파악.
질문: "이상 있나?"
Traces (추적)
요청의 전체 여정 — Agent→Model→Tool→External 각 스팬의 시간과 결과.
질문: "어디가 문제?"
Logs (로그)
이벤트 기록 — 프롬프트 입출력, 도구 파라미터, 에러 상세.
질문: "왜 발생했나?"
세 질문에 순서대로 답합니다 — Metrics가 "이상 있나", Traces가 "어디가", Logs가 "왜"를 맡습니다.
에이전트 Trace 구조
하나의 요청이 여러 스팬으로 분해됨 — 계층적 구조
Agent Loop Span
전체 에이전트 실행 (루트 스팬) — 총 지연, 사이클 수
Model Invoke Span
LLM 추론 호출 — 토큰 수, 모델 ID, 지연
Tool Execute Span
도구 실행 — 도구명, 파라미터, 응답, 지연
External Call Span
도구 내부 외부 API 호출 — HTTP 상태, 지연
OpenTelemetry 통합
Strands 자동 계측 · ADOT · X-Ray · CloudWatch
OpenTelemetry 통합
설치부터 X-Ray·CloudWatch 전송까지 자동 계측 파이프라인의 조감
Strands 자동 계측 → ADOT → X-Ray · CloudWatch
계측 코드를 직접 작성하지 않고 SDK가 스팬을 자동 생성해 AWS 백엔드로 보냅니다.
- pip install "strands-agents[otel]" — 자동 스팬 생성
- StrandsTelemetry().setup_otlp_exporter() — 1줄 활성화
- ADOT Collector — X-Ray(트레이스) + CloudWatch(메트릭)
- gen_ai.* — 벤더 중립 GenAI Semantic Conventions
설치 한 줄과 활성화 한 줄로 Agent loop·Model invoke·Tool execute 스팬이 자동 생성됩니다 — 파이프라인의 종착지는 X-Ray와 CloudWatch입니다.
ADOT 파이프라인
Agent → ADOT Collector → X-Ray·CloudWatch 전송 아키텍처
Strands 자동 계측 코드
pip install "strands-agents[otel]" → StrandsTelemetry 1줄로 활성화
from strands import Agent
from strands.telemetry import StrandsTelemetry
# ① OTel OTLP Exporter 활성화 — 1줄
StrandsTelemetry().setup_otlp_exporter()
# ② 에이전트 코드는 무변경
agent = Agent(model=model, tools=[search])
agent("서울 맛집 추천해줘")
# ③ → Agent loop, Model invoke, Tool execute 스팬 자동 생성
# → ADOT Collector → X-Ray + CloudWatch로 자동 전송- 활성화 1줄 — pip install "strands-agents[otel]" 후 setup_otlp_exporter() 호출이 전부. 계측 코드 직접 작성 없음
- 에이전트 무변경 — 기존 Agent 그대로. 모델 호출·도구 실행이 자동으로 계측 대상
- 전송 경로 — 스팬 3종이 gen_ai.* 표준 어트리뷰트로 ADOT Collector를 거쳐 X-Ray(트레이스)·CloudWatch(메트릭)에 적재
GenAI Semantic Conventions
OTel 표준의 AI 전용 어트리뷰트 — 벤더 중립으로 기록
| 어트리뷰트 | 설명 | 예시 값 |
|---|---|---|
| gen_ai.provider.name | 모델 프로바이더 | anthropic |
| gen_ai.request.model | 요청 모델 ID | us.anthropic.claude-sonnet-4-6 |
| gen_ai.response.finish_reasons | 종료 사유 (배열) | ["end_turn"] |
| gen_ai.usage.input_tokens | 입력 토큰 수 | 1,234 |
| gen_ai.usage.output_tokens | 출력 토큰 수 | 567 |
gen_ai.* 어트리뷰트는 OTel 표준이라 프로바이더를 바꿔도 같은 키로 조회할 수 있습니다 — 벤더 중립 계측의 핵심입니다.
Golden Signals
Latency · Traffic · Errors · Saturation + Cost
Golden Signals
SRE 4대 시그널에 에이전트 특화 지표를 더한 감시 체계의 조감
Golden Signals + Cost
Google SRE 4대 시그널에 에이전트 특화 지표를 더해 상태를 진단합니다.
- Latency · Traffic · Errors · Saturation — SRE 4대 시그널
- Cost — 세션당 토큰 비용 · 일간 누적 비용
- ToolCallsPerInvocation · LoopIterations — 루프 이상 징후
- CacheHitRate · SessionCompletionRate — 효율과 품질
4대 시그널이 서비스 일반의 건강을 재고, Cost와 루프 지표가 에이전트 고유의 이상을 잡아냅니다.
Google SRE 4대 시그널 + Cost
4대 시그널에 에이전트 특화 Cost를 추가 — 5개로 상태 진단
- Latency
- P95 응답 시간 (LLM + 도구 포함)
- Traffic
- 초당 세션 수, 분당 도구 호출 수
- Errors
- 실패율 (timeout + throttle + exception)
- Saturation
- 동시 세션 / 최대 용량 비율
- Cost
- 세션당 토큰 비용, 일간 누적 비용
Google SRE 4대 시그널에 Cost를 더한 5개 지표가 에이전트 상태 진단의 출발점입니다.
에이전트 전용 메트릭
Golden Signals로 잡히지 않는 에이전트 고유 지표
| 메트릭 | 설명 | 알람 기준 예시 |
|---|---|---|
| ToolCallsPerInvocation | 요청당 평균 도구 호출 수 | > 10 (무한 루프 징후) |
| TokensPerRequest | 요청당 총 토큰 | > 100K (비용 폭증) |
| LoopIterations | 에이전트 루프 반복 수 | > 15 (탈출 실패) |
| CacheHitRate | Prompt Caching 적중률 | < 50% (비효율) |
| SessionCompletionRate | 목표 달성 정상 종료 비율 | < 70% (품질 저하) |
표의 알람 기준은 예시입니다 — 루프 징후·비용 폭증·캐시 효율·완료율처럼 Golden Signals가 놓치는 에이전트 고유 신호를 보완합니다.
프로덕션 대시보드
CloudWatch 4패널 · 알람 · 인시던트 플레이북
프로덕션 대시보드
4패널 대시보드·알람·플레이북으로 완성하는 운영 체계의 조감
CloudWatch 4패널 + 알람 + 플레이북
대시보드가 상태를 보여주고, 알람이 이상을 알리고, 플레이북이 대응을 정합니다.
- 4패널 — Overview · Model · Tool · Cost
- 알람 패턴 — P95 > 5s Warning · Error > 2% Critical
- 인시던트 플레이북 — 지연 · 에러 · 비용 · 무한루프 대응
- boto3 put_metric_alarm — 호출량 알람 코드
앞 파트의 계측과 지표가 여기서 운영팀이 쓰는 화면과 대응 절차로 완성됩니다.
CloudWatch 4패널 대시보드
에이전트 운영팀이 한눈에 상태를 파악하는 화면 구성
console.aws.amazon.com/cloudwatch — Dashboards › agent-prod
12,438 요청/일
99.2% 성공률
3.1s P95 지연
알람과 인시던트 플레이북
임계값 초과 시 자동 알림 → 플레이북 실행으로 대응
알람 설정 패턴
- P95 Latency > 5s → Warning
- Error Rate > 2% → Critical
- Token Cost > 일예산 80% → Warning
- Loop Iterations > 15 → Critical (무한루프)
대응 플레이북
- 지연 증가 → 모델 다운그레이드 또는 캐시 확인
- 에러 급증 → 도구 헬스체크, 모델 상태 확인
- 비용 초과 → Prompt Routing 활성화, 모델 스위치
- 무한루프 → Hooks 상한 카운터(BeforeToolCallEvent → event.cancel_tool) 정책 점검, 프롬프트 검토
CloudWatch 알람 코드
boto3로 Bedrock 모델 호출량 알람을 직접 생성
import boto3
cloudwatch = boto3.client("cloudwatch", region_name="us-east-1")
cloudwatch.put_metric_alarm(
AlarmName="bedrock-agent-loop-alert",
# ① AWS/Bedrock 네임스페이스의 Invocations(호출 수) 메트릭
MetricName="Invocations",
Namespace="AWS/Bedrock",
Dimensions=[{"Name": "ModelId", "Value": "us.anthropic.claude-sonnet-4-6"}],
# ② 일간 호출 10,000건 초과 시 — 무한루프·폭주를 조기 감지
Threshold=10000,
ComparisonOperator="GreaterThanThreshold",
EvaluationPeriods=1,
Period=86400, # 일간
Statistic="Sum",
# ③ 초과 시 SNS 토픽으로 알림
AlarmActions=["arn:aws:sns:us-east-1:123456789012:agent-alert"],
)- 메트릭 선택 — AWS/Bedrock의 Invocations를 ModelId 차원으로 좁혀 특정 모델 호출량만 감시
- 임계값 — Period=86400(일간) 합계가 10,000건을 넘으면 알람 상태. 폭주·무한루프 조기 감지
- AlarmActions — SNS 토픽으로 알림 발송 → 앞의 인시던트 플레이북 대응으로 연결
관측성 실습
gen_ai 어트리뷰트 확인부터 Golden Signals 대시보드·이상 탐지 알람까지 구축합니다
학습 목표
- Strands 스팬의 gen_ai.* 표준 어트리뷰트 확인
- Golden Signals 메트릭 CloudWatch 발행
- 4패널 대시보드 구성
- 루프 폭주·도구 실패 탐지 알람 설정
Traces(어디가 문제) · Metrics(이상 있나) · Logs(왜 발생했나) = 3축 관측