Strands 관측성

관측성 파이프라인 전체 흐름

SDK 계측부터 백엔드 시각화까지 — 데이터가 흐르는 경로

1. 1
   SDK 계측

   StrandsTelemetry가 Agent Loop, Model Invoke, Tool Execute 각 단계에 자동으로 스팬과 메트릭을 생성. 코드 수정 없이 1줄 설정으로 활성화.

2. 2
   Exporter 전송

   OTel SDK의 OTLP Exporter가 스팬·메트릭·로그를 gRPC 또는 HTTP/protobuf로 Collector에 전송 — StrandsTelemetry의 setup_otlp_exporter는 HTTP/protobuf(4318) 고정. 배치 처리로 네트워크 효율 확보.

3. 3
   Collector 처리

   ADOT Collector가 수신된 텔레메트리를 배치·필터·샘플링 처리. 민감 정보 제거, 어트리뷰트 보강 등 전처리 수행.

4. 4
   Backend 저장/시각화

   X-Ray에 트레이스, CloudWatch에 메트릭과 로그 저장. 서비스 맵, 대시보드, 알람으로 운영자에게 가시성 제공.

관측성 3 Pillars

세 축이 결합되어야 "어디서, 무엇이, 왜" 발생했는지 파악 가능

StrandsTelemetry 초기화

1줄 설정으로 에이전트 전체 자동 계측 활성화

핵심 포인트

StrandsTelemetry()

텔레메트리 진입점 — setup_* 메서드 체이닝으로 활성화

setup_otlp_exporter()

OTLP 전송 — HTTP/protobuf 전용(4318 포트), gRPC 아님

setup_console_exporter()

스팬 콘솔 출력 — Collector 없이 로컬 디버그

setup_meter()

OTel Meter 활성화 — 커스텀 메트릭의 기반

OTEL_TRACES_SAMPLER

SDK 측 샘플링(traceidratio) — 비율은 SAMPLER_ARG=0.5

gen_ai_span_attributes_only

gen_ai.* 어트리뷰트만 내보내는 환경 변수 옵션

자동 계측

invoke_agent · chat · execute_tool 스팬 + 토큰·지연 메트릭 자동 생성

코드

from strands import Agent
from strands.telemetry import StrandsTelemetry
from strands.models import BedrockModel

# Exporter + Meter 활성화 — 메서드 체이닝, HTTP/protobuf 전용
# 전송 대상: export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
StrandsTelemetry().setup_otlp_exporter() \
    .setup_meter(enable_otlp_exporter=True)

# 에이전트 조립·실행 — 이후 모든 호출이 자동 계측됨
agent = Agent(
    model=BedrockModel(model_id="us.anthropic.claude-sonnet-4-6"),
    tools=[search, calculate],
)
result = agent("최근 3개월 AWS 비용 추이를 분석해줘")
# → invoke_agent / execute_event_loop_cycle / chat / execute_tool
#   스팬 자동 생성 + 토큰·지연·도구 호출 횟수 메트릭 자동 발행

트레이싱

자동 계측이 만든 스팬 트리 위에 커스텀 스팬·속성을 얹는 확장

커스텀 스팬과 어트리뷰트

OTel tracer API로 도구 내부에 커스텀 스팬과 속성을 추가

핵심 포인트

trace.get_tracer

OTel tracer 획득 — 커스텀 스팬 생성의 진입점

start_as_current_span

with 블록으로 자식 스팬 생성 — 도구 내부 구간을 독립 계측

set_attribute

질의 · top_k · 결과 수 같은 비즈니스 속성을 스팬에 기록

trace_attributes

Agent 트레이스 전체에 공통 속성 부여 — session.id 등

코드

from strands import Agent, tool
from opentelemetry import trace

tracer = trace.get_tracer("my-agent")  # 커스텀 스팬의 진입점

@tool
def knowledge_search(query: str, top_k: int = 5) -> list:
    """지식 베이스에서 관련 문서를 검색합니다."""
    with tracer.start_as_current_span("kb_retrieve") as span:
        span.set_attribute("search.query", query)
        span.set_attribute("search.top_k", top_k)
        results = bedrock_kb.retrieve(query=query, top_k=top_k)
        span.set_attribute("search.result_count", len(results))
    return results

# Agent에 트레이스 공통 속성 전달
agent = Agent(tools=[knowledge_search],
              trace_attributes={"session.id": "abc-123"})

Span 계층 구조

하나의 에이전트 호출이 스팬 트리로 분해되는 구조 — 부모가 자식을 포함

트레이스 워터폴 — 실물

요청 하나가 남긴 스팬 계단 — cost-analyzer 에이전트의 3사이클, 4,200ms

Trace Attributes 스키마

GenAI Semantic Conventions 표준(gen_ai.*) + 커스텀 비즈니스 속성 — 두 층이 합쳐져 검색 가능한 트레이스

스팬 리댁션 — 민감 정보 마스킹

허용목록 밖 프롬프트·응답 원문을 SDK가 스팬 생성 시점에 차단 — python v1.47.0부터 지원

핵심 포인트

[REDACTED]

허용목록에 없으면 gen_ai.input.messages · gen_ai.output.messages · gen_ai.system_instructions 값이 이 문자열로 치환

허용목록(glob)

semconv 전환과 같은 환경 변수에 gen_ai_unredacted_attributes= 토큰 추가 — glob 패턴으로 원문 유지 대상 지정

SDK 원천 차단

스팬 생성 시점에 마스킹 — 원문이 Exporter · Collector · 백엔드 어디에도 도달하지 않음

Collector 필터와 대비

attributes · filter processor는 수집 후 파이프라인에서 제거 — 전송 구간에는 원문 노출. 리댁션은 SDK에서 먼저 자름

코드

# 최신 semconv 모드 — 메시지 본문 어트리뷰트는 기본 리댁션
export OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental
# span: gen_ai.input.messages       = [REDACTED]
#       gen_ai.output.messages      = [REDACTED]
#       gen_ai.system_instructions  = [REDACTED]

# 허용목록(glob) 지정 — 출력 메시지만 원문 유지
export OTEL_SEMCONV_STABILITY_OPT_IN="gen_ai_latest_experimental,\
gen_ai_unredacted_attributes=gen_ai.output.*"
# span: gen_ai.input.messages       = [REDACTED]
#       gen_ai.output.messages      = [{"role": "assistant", ...}]

메트릭과 비용

호출 결과에서 바로 꺼내는 수치와, 그 위에 쌓는 운영 메트릭

result.metrics 즉시 확인

에이전트 호출 결과에서 토큰·지연·비용 메트릭을 즉시 추출

from strands import Agent

# 에이전트 조립·실행 — 별도 설정 없이 메트릭 자동 수집
agent = Agent(model="us.anthropic.claude-sonnet-4-6", tools=[search])
result = agent("최근 보안 취약점 요약해줘")

# result.metrics — EventLoopMetrics 객체, 호출 즉시 확인 가능
usage = result.metrics.accumulated_usage       # 키는 camelCase
print(usage["inputTokens"])                    # 2340
print(usage["outputTokens"])                   # 891
print(usage["totalTokens"])                    # 3231
# accumulated_*는 에이전트 재사용 시 전 요청 누적 —
# 요청 단위는 latest_agent_invocation·agent_invocations로 추출

# 누적 지연·사이클 수·도구별 메트릭·요약 dict
print(result.metrics.accumulated_metrics["latencyMs"])  # 4520
print(result.metrics.cycle_count)                       # 2
print(result.metrics.tool_metrics)                      # 도구별 호출 통계
print(result.metrics.get_summary())                     # 사람이 읽기 좋은 집계

# 비용 계산 (Claude Sonnet 기준)
cost = (usage["inputTokens"] * 3 + usage["outputTokens"] * 15) / 1_000_000
print(f"이번 호출 비용: ${cost:.4f}")  # $0.0204

핵심 메트릭 지표

에이전트 운영에서 반드시 추적해야 하는 수치

메트릭 수집 위치별 분류

SDK 자동 수집 vs CloudWatch 자동 발행 vs 커스텀 정의 구분

ADOT Collector 아키텍처

Agent에서 X-Ray·CloudWatch까지 텔레메트리가 흐르는 경로

1. 1
   Strands Agent

   StrandsTelemetry가 계측한 스팬·메트릭을 OTel SDK가 수집. OTLP 프로토콜로 직렬화하여 Collector에 전송 준비.

2. 2
   OTel SDK (Exporter)

   BatchSpanProcessor가 스팬을 배치로 모아 전송. StrandsTelemetry의 OTLPSpanExporter는 HTTP/protobuf(4318)로 Collector에 push — Collector 수신부는 gRPC 4317도 함께 열 수 있음.

3. 3
   ADOT Collector

   Receiver(OTLP) → Processor(batch, filter, attributes) → Exporter(awsxray, awsemf) 3단 파이프라인. ECS Sidecar 또는 EC2 데몬으로 배포.

4. 4
   X-Ray + CloudWatch

   X-Ray가 트레이스를 저장하고 서비스 맵을 생성. CloudWatch가 메트릭을 저장하고 대시보드·알람을 구동.

ADOT Collector 설정

otel-collector-config.yaml — Receiver, Processor, Exporter 3단 구성

핵심 포인트

receivers.otlp

SDK가 보내는 텔레메트리 수신 — gRPC 4317 · HTTP 4318

processors.batch

5초 · 256개 배치 묶음 — filter를 추가하면 헬스체크 스팬 제외 같은 전처리 가능

exporters

awsxray는 트레이스를 X-Ray로, awsemf는 메트릭을 CloudWatch EMF로 발행

service.pipelines

traces · metrics 경로를 각각 Receiver → Processor → Exporter로 조립

코드

receivers:
  otlp:
    protocols:
      grpc: { endpoint: 0.0.0.0:4317 }
      http: { endpoint: 0.0.0.0:4318 }
processors:
  batch: { timeout: 5s, send_batch_size: 256 }
exporters:
  awsxray: { region: us-east-1 }
  awsemf:
    region: us-east-1
    namespace: StrandsAgent
    log_group_name: /strands/agent/metrics
service:
  pipelines:
    traces:
      {receivers: [otlp], processors: [batch], exporters: [awsxray]}
    metrics:
      {receivers: [otlp], processors: [batch], exporters: [awsemf]}

대시보드 구성요소

운영팀이 에이전트 상태를 한눈에 파악하는 4패널 구성

메트릭 대시보드 — 실물

Strands가 내보낸 gen_ai.* · strands.* 데이터가 CloudWatch 4패널에서 읽히는 모습 (예시 수치)