View a markdown version of this page

AI 관찰성 - Amazon OpenSearch Service
시작하기에이전트 추적 UI

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

AI 관찰성

OpenSearch의 AI 관찰성은 AI 에이전트 및 대규모 언어 모델(LLM) 워크플로를 모니터링, 디버깅 및 최적화하기 위한 end-to-end 도구를 제공합니다. GenAI 의미 체계 규칙을 기반으로 하며 OpenTelemetry(OTel)와 기본적으로 통합되므로 프로덕션 환경에서 AI 애플리케이션이 작동하는 방식을 완벽하게 파악할 수 있습니다.

AI 관찰성에는 다음 기능이 포함됩니다.

  • 에이전트 추적 - 에이전트 오케스트레이션 단계, LLM 호출, 도구 호출 및 검색 작업 전반에서 계층적 실행 추적을 캡처합니다.

  • GenAI 의미 체계 규칙 - gen_ai.system, gen_ai.request.model및와 같은 표준화된 OTel 속성을 사용하여 AI별 원격 측정을 gen_ai.usage.input_tokens 설명합니다.

  • 자동 계측 - OpenAI, Anthropic, Amazon Bedrock, LangChain 및 20개 이상의 추가 라이브러리를 포함하여 널리 사용되는 AI 프레임워크 및 공급자의 트레이스를 자동으로 캡처합니다.

  • PPL 쿼리 - OpenSearch UI에서 직접 파이프 처리 언어(PPL)를 사용하여 추적 데이터를 쿼리하고 집계합니다.

시작하기

이 섹션에서는 AI 에이전트를 계측하고, Amazon OpenSearch Service로 트레이스를 전송하고, OpenSearch UI에서 트레이스를 보는 방법을 안내합니다.

SDK를 설치하려면

OpenTelemetry GenAI 계측 패키지를 설치합니다.

pip install opentelemetry-instrumentation-openai-v2 opentelemetry-sdk opentelemetry-exporter-otlp

에이전트 코드를 계측하려면

다음 예제에서는 OTel SDK를 등록하고, @observe 데코레이터로 에이전트 함수에 주석을 달고, GenAI 속성으로 스팬을 보강하는 방법을 보여줍니다.

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import OTLPSpanExporter

# Register the tracer provider
provider = TracerProvider()
processor = BatchSpanProcessor(
    OTLPSpanExporter(endpoint="<your-osis-endpoint>")  # Use your OpenSearch Ingestion endpoint with SigV4
)
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)

tracer = trace.get_tracer(__name__)

# Decorate your agent function
@observe
def run_agent(prompt: str):
    with tracer.start_as_current_span("invoke_agent") as span:
        span.set_attribute("gen_ai.operation.name", "invoke_agent")
        span.set_attribute("gen_ai.system", "openai")
        span.set_attribute("gen_ai.request.model", "gpt-4")

        # Enrich with token usage after the LLM call
        response = call_llm(prompt)
        span.set_attribute("gen_ai.usage.input_tokens", response.input_tokens)
        span.set_attribute("gen_ai.usage.output_tokens", response.output_tokens)
        return response
참고

Amazon OpenSearch Service로 추적을 전송할 때는 로컬 호스트 엔드포인트 대신 SigV4 인증과 함께 OpenSearch Ingestion 파이프라인 엔드포인트를 사용합니다. OpenSearch Ingestion 파이프라인 구성에 대한 자세한 내용은 섹션을 참조하세요Amazon OpenSearch Ingestion 개요.

OpenSearch UI에서 트레이스를 보려면

계측된 애플리케이션이 추적 데이터를 전송한 후 OpenSearch UI에서 탐색할 수 있습니다. 관찰성 워크스페이스의 왼쪽 탐색 창에서 검색을 확장하고 에이전트 추적을 선택합니다.

에이전트 추적 UI

OpenSearch UI의 에이전트 추적 페이지는 LLM 에이전트 실행 추적을 탐색, 디버깅 및 모니터링하기 위해 특별히 구축된 인터페이스를 제공합니다. 개발자와 플랫폼 운영자에게 계층적 트레이스 보기, 세부 정보 플라이아웃, 흐름 시각화, 집계 지표 등 에이전트 AI 애플리케이션에 대한 완전한 관찰성을 제공합니다.

아키텍처

다음 다이어그램은 계측된 애플리케이션에서 에이전트 추적 UI로의 데이터 흐름을 보여줍니다.

LLM Application (with OTel SDK + GenAI instrumentation)
    |
    |  OTLP (gRPC/HTTP)
    v
OTel Collector (batch, transform)
    |
    +---- OTLP ----> OpenSearch Ingestion --> OpenSearch (otel-v1-apm-span-*)
    |
    +---- Prometheus Remote Write --> Prometheus (metrics)
                                          |
                                          v
                              OpenSearch UI
                              +-- Agent Traces Plugin

사전 조건

에이전트 추적을 사용하기 전에 다음이 있는지 확인합니다.

  • otel-v1-apm-span-* 인덱스로 인덱싱된 추적 데이터가 있는 OpenSearch 클러스터입니다.

  • LLM 애플리케이션에서 GenAI 의미 체계 규칙이 활성화된 OpenTelemetry 계측.

  • 스팬을 OpenSearch로 수집하도록 otel_trace_raw 프로세서로 구성된 OpenSearch Ingestion입니다.

  • OpenSearch UI에서 PPL 쿼리 지원이 활성화되었습니다.

필수 스팬 속성

에이전트 추적은 추적 데이터를 올바르게 렌더링하기 위해 특정 스팬 속성이 필요합니다. 다음 표에서는 코어 필드와 GenAI별 속성을 설명합니다.

코어 스팬 필드

각 스팬에는 다음 코어 필드가 포함되어야 합니다.

Field Type 설명
traceId 문자열 전체 트레이스의 고유 식별자입니다.
spanId 문자열 이 범위의 고유 식별자입니다.
parentSpanId 문자열 상위 스팬의 식별자입니다. 루트 범위의 경우 비어 있습니다.
startTime 타임스탬프 스팬이 시작된 시간입니다.
endTime 타임스탬프 스팬이 종료된 시간입니다.
durationInNanos Long 나노초 단위의 범위 지속 시간입니다.
status.code Integer 범위 상태 코드(0 = 설정되지 않음, 1 = 정상, 2 = 오류).
GenAI 속성

다음 gen_ai.* 속성은 에이전트 추적 UI에서 AI별 기능을 활성화합니다.

속성 값 예 설명
gen_ai.operation.name chat GenAI 작업의 유형입니다. 스팬 범주를 결정합니다.
gen_ai.system openai AI 시스템 또는 공급자입니다.
gen_ai.request.model gpt-4 요청에 사용되는 모델입니다.
gen_ai.usage.input_tokens 150 사용된 입력 토큰 수입니다.
gen_ai.usage.output_tokens 85 생성된 출력 토큰 수입니다.
gen_ai.response.finish_reasons ["stop"] 모델 생성을 중지한 이유입니다.

페이지 레이아웃 및 지표 표시줄

에이전트 추적 페이지에는 표시되는 모든 추적에 대한 주요 통계를 요약하는 지표 표시줄이 상단에 표시됩니다. 지표에는 총 추적 수, 평균 기간, 오류율 및 토큰 사용량이 포함됩니다. 이러한 값은 시간 필터 및 쿼리에 따라 동적으로 업데이트됩니다.

트레이스 탭

추적 탭에는 현재 쿼리 및 시간 범위와 일치하는 모든 루트 에이전트 추적이 나열됩니다. 각 행은 단일 에이전트 호출을 나타냅니다.

다음 표에서는 트레이스 테이블의 열을 설명합니다.

열 설명
트레이스 ID 트레이스의 고유 식별자입니다. 링크를 선택하여 트레이스 세부 정보 플라이아웃을 엽니다.
에이전트 이름 추적을 시작한 에이전트의 이름입니다.
Status 전체 추적 상태(OK 또는 오류).
지속 시간 추적의 첫 번째 범위부터 마지막 범위까지의 총 시간입니다.
스팬 추적의 총 스팬 수입니다.
입력 토큰 추적의 모든 LLM 호출에서 사용된 총 입력 토큰입니다.
출력 토큰 추적의 모든 LLM 호출에서 생성된 총 출력 토큰입니다.
시작 시간 추적이 시작된 시점의 타임스탬프입니다.

범위 범주

스팬은 gen_ai.operation.name 속성에 따라 분류됩니다. 각 범주는 UI에 고유한 색상과 아이콘으로 표시됩니다.

작업 이름 범주 설명
invoke_agent, create_agent 에이전트 에이전트 오케스트레이션 단계.
chat LLM LLM 채팅 완료 호출.
text_completion, generate_content 내용 텍스트 생성 작업.
execute_tool 도구 도구 호출.
embeddings 임베딩 임베딩 생성.
retrieval 검색 데이터 검색 작업.

스팬 탭

스팬 탭에는 모든 트레이스의 개별 스팬이 표시됩니다. 범위를 필터링하고 정렬하여 특정 작업을 찾을 수 있습니다.

트레이스 세부 정보 플라이아웃

트레이스 ID를 선택하면 다음 두 가지 주요 영역이 있는 플라이아웃 패널이 열립니다.

  • 왼쪽 패널 - 범위 간의 계층적 상위-하위 관계를 보여주는 트레이스 트리를 표시합니다. 또한 에이전트의 실행 경로를 시각화하는 흐름 DAG(방향성 비순환 그래프)도 포함되어 있습니다.

  • 오른쪽 패널 - 두 개의 탭이 있습니다. 세부 정보 탭에는 스팬 속성, 리소스 속성 및 GenAI별 메타데이터가 표시됩니다. 타임라인 탭에는 스팬 기간 및 타이밍 관계의 폭포형 차트가 표시됩니다.

추적 쿼리

에이전트 추적은 모든 데이터 가져오기에 PPL(Piped Processing Language)을 사용합니다. 페이지 상단의 쿼리 패널에서 쿼리를 작성할 수 있습니다.

루트 추적을 나열하려면

다음 쿼리는 가장 최근의 루트 에이전트 추적 100개를 반환합니다.

source = otel-v1-apm-span-*
| where parentSpanId = "" AND isnotnull(`attributes.gen_ai.operation.name`)
| sort - startTime
| head 100
추적에 대한 모든 스팬을 가져오려면

다음 쿼리는 특정 트레이스에 대한 전체 스팬 트리를 반환합니다.

source = otel-v1-apm-span-*
| where traceId = "trace-id"
| head 1000
집계 지표를 계산하려면

다음 쿼리는 모델별로 그룹화된 평균 기간 및 총 토큰 사용량을 계산합니다.

source = otel-v1-apm-span-*
| where isnotnull(`attributes.gen_ai.request.model`)
| stats avg(durationInNanos) as avg_duration,
        sum(`attributes.gen_ai.usage.input_tokens`) as total_input_tokens,
        sum(`attributes.gen_ai.usage.output_tokens`) as total_output_tokens
    by `attributes.gen_ai.request.model`