OpenTelemetry 트레이싱

OpenTelemetry 트레이싱 (OpenTelemetry)

OpenTelemetry로 Haystack 파이프라인을 트레이스하는 방법을 알아볼게요.

출처: OpenTelemetry (공식 문서)

개요 (Overview)

OpenTelemetry는 트레이스, 메트릭, 로그를 수집하는 오픈소스 옵저버빌리티(observability) 프레임워크예요. Haystack은 OpenTelemetry와 통합되므로, 파이프라인 실행의 트레이스를 어떤 OpenTelemetry 호환 백엔드로든 보낼 수 있어요.

Provided by an integration

OpenTelemetryTracer는 opentelemetry-haystack 패키지에 있으며 Haystack 코어의 일부가 아니에요. Haystack 3.0부터 OpenTelemetry 트레이싱은 opentelemetry-sdk가 설치되어 있어도 더 이상 자동 활성화되지 않습니다. 통합 패키지를 설치하고 OpenTelemetryTracer를 직접 켜거나 OpenTelemetryConnector 컴포넌트를 파이프라인에 추가해야 해요.

설치 (Installation)

opentelemetry-haystack 패키지를 설치하세요.

pip install opentelemetry-haystack

파이프라인의 더 깊은 계층까지 트레이스를 추가하고 싶다면 OpenTelemetry 통합을 살펴보길 권해요. 예를 들어:

• 파이프라인에서 HTTP 요청을 트레이스하는 urllib3 instrumentation,
• OpenAI 요청을 트레이스하는 OpenAI instrumentation.

사전 요구사항 (Prerequisites)

exporter가 있는 구성된 OpenTelemetry TracerProvider가 필요해요. 예를 들어 트레이스를 수집기나 백엔드로 보내는 OTLP exporter라면 됩니다. 트레이서를 켜기 전에 provider를 설정해 두세요.

사용법 (Usage)

파이프라인에 컴포넌트를 추가하지 않고도 OpenTelemetryTracer를 직접 켜서 어떤 Haystack 파이프라인이든 트레이스할 수 있어요. TracerProvider를 구성하고 Haystack 컴포넌트를 import하기 전에 HAYSTACK_CONTENT_TRACING_ENABLED 환경 변수를 설정하세요.

import os

os.environ["HAYSTACK_CONTENT_TRACING_ENABLED"] = "true"

from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.semconv.resource import ResourceAttributes

# Configure the OpenTelemetry SDK. A service name is required for most backends.
resource = Resource(attributes={ResourceAttributes.SERVICE_NAME: "haystack"})
tracer_provider = TracerProvider(resource=resource)
tracer_provider.add_span_processor(
    BatchSpanProcessor(OTLPSpanExporter(endpoint="http://localhost:4318/v1/traces")),
)
trace.set_tracer_provider(tracer_provider)

from haystack import tracing
from haystack_integrations.tracing.opentelemetry import OpenTelemetryTracer

# Enable the OpenTelemetry tracer
tracing.enable_tracing(OpenTelemetryTracer(trace.get_tracer("my_application")))

그러면 각 파이프라인 실행이 전체 실행 컨텍스트(프롬프트, 완성(completions), 메타데이터 포함)를 담은 트레이스를 만들고, OpenTelemetry 호환 백엔드에서 그 트레이스를 확인할 수 있어요.

대안: OpenTelemetryConnector 컴포넌트

트레이싱을 파이프라인 정의의 일부로 관리하고 싶다면, OpenTelemetryConnector 컴포넌트를 추가하는 방법도 있어요. 초기화되는 즉시 동일한 OpenTelemetry 트레이싱을 켭니다.

info

전체 사용 예시는 OpenTelemetryConnector 문서 페이지를, 통합 페이지도 참고하세요.

개발 중 트레이스 시각화 (Visualizing Traces During Development)

로컬 파이프라인 개발용으로 Jaeger를 가벼운 트레이싱 백엔드로 쓸 수 있어요. 복잡한 트레이싱 백엔드 없이 트레이싱을 실험해볼 수 있죠.

1. Jaeger 컨테이너를 실행하세요. 그러면 트레이싱 백엔드와 트레이스를 시각화할 UI가 함께 만들어집니다.

docker run --rm -d --name jaeger \
    -e COLLECTOR_ZIPKIN_HOST_PORT=:9411 \
    -p 6831:6831/udp \
    -p 6832:6832/udp \
    -p 5778:5778 \
    -p 16686:16686 \
    -p 4317:4317 \
    -p 4318:4318 \
    -p 14250:14250 \
    -p 14268:14268 \
    -p 14269:14269 \
    -p 9411:9411 \
    jaegertracing/all-in-one:latest

2. 통합 패키지와 OTLP exporter를 설치하세요.

pip install opentelemetry-haystack
pip install opentelemetry-exporter-otlp

3. OpenTelemetry가 Jaeger 백엔드를 쓰도록 구성하고 트레이서를 켜세요.

from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.semconv.resource import ResourceAttributes

from haystack import tracing
from haystack_integrations.tracing.opentelemetry import OpenTelemetryTracer

# Service name is required for most backends
resource = Resource(attributes={ResourceAttributes.SERVICE_NAME: "haystack"})

tracer_provider = TracerProvider(resource=resource)
processor = BatchSpanProcessor(
    OTLPSpanExporter(endpoint="http://localhost:4318/v1/traces")
)
tracer_provider.add_span_processor(processor)
trace.set_tracer_provider(tracer_provider)

tracing.enable_tracing(OpenTelemetryTracer(trace.get_tracer("my_application")))

4. 파이프라인을 실행하세요.

...
pipeline.run(...)
...

5. Jaeger가 제공하는 UI인 http://localhost:16686에서 트레이스를 확인하세요.

더 알아보기 (Learn more)

• OpenTelemetry - 공식 문서
• OpenTelemetryConnector
• Tracing