OpenTelemetryConnector

Haystack에서 OpenTelemetry를 사용하는 방법을 배워요.

출처: 문서

본문

OpenTelemetryConnector는 OpenTelemetry와 OpenTelemetry SDK를 통해 Haystack 파이프라인에 추적(tracing) 기능을 통합해요. API 호출, 컨텍스트 데이터, 프롬프트 등 파이프라인 실행의 상세 정보를 포착해서, OpenTelemetry와 호환되는 어떤 백엔드에서든 파이프라인 실행의 전체 트레이스를 확인할 수 있게 해 줘요.

OpenTelemetryConnector가 초기화되는 순간 OpenTelemetry 추적이 활성화되므로, 파이프라인에 추가만 하면 돼요. 다른 컴포넌트에 연결하거나 실행할 필요가 없어요.

선택적으로 이 추적 컴포넌트를 식별할 name을 넘길 수 있어요(기본값은 opentelemetry예요).

사전 요구 사항

OpenTelemetryConnector를 쓰기 전에 필요한 것들이 있어요.

익스포터가 설정된 OpenTelemetry TracerProvider(예: 트레이스를 컬렉터나 백엔드로 보내는 OTLP 익스포터). 커넥터를 초기화하기 전에 프로바이더를 설정하세요.
HAYSTACK_CONTENT_TRACING_ENABLED 환경 변수를 true로 설정 — 이렇게 하면 파이프라인에서 콘텐츠 추적(입력과 출력)이 활성화돼요.
더 깊은 수준의 트레이스를 추가하려면 OpenAI 요청을 추적하는 opentelemetry-instrumentation-openai-v2 같은 사용 가능한 OpenTelemetry 계측(instrumentations)을 확인하세요.

설치

OpenTelemetryConnector를 쓰려면 먼저 opentelemetry-haystack 패키지를 설치해요.

pip install opentelemetry-haystack

사용 주의: 올바른 추적을 위해 항상 Haystack 컴포넌트를 임포트하기 전에 환경 변수를 설정하세요. Haystack은 임포트 중에 내부 추적 컴포넌트를 초기화하므로 이게 중요해요. 아래 예제에서는 먼저 환경 변수를 설정한 뒤 관련 Haystack 컴포넌트를 임포트해요.

더 좋은 방법은 스크립트를 실행하기 전에 셸에서 환경 변수를 설정하는 거예요. 이렇게 하면 설정이 코드와 분리되고 다른 환경을 더 쉽게 관리할 수 있어요.

더 알아보기 (Learn more)

아래 예제에서는 OpenTelemetryConnector를 tracer 로 파이프라인에 추가해요. 각 파이프라인 실행은 프롬프트·완성·메타데이터를 포함한 전체 실행 컨텍스트가 담긴 트레이스를 생성해요. 그런 다음 OpenTelemetry 백엔드에서 트레이스를 볼 수 있어요.

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 Pipeline
from haystack.components.builders import ChatPromptBuilder
from haystack.components.generators.chat import OpenAIChatGenerator
from haystack.dataclasses import ChatMessage

from haystack_integrations.components.connectors.opentelemetry import (
    OpenTelemetryConnector,
)


pipe = Pipeline()
pipe.add_component("tracer", OpenTelemetryConnector("Chat example"))
pipe.add_component("prompt_builder", ChatPromptBuilder())
pipe.add_component("llm", OpenAIChatGenerator())
pipe.connect("prompt_builder.prompt", "llm.messages")

messages = [
    ChatMessage.from_system(
        "Always respond in German even if some input data is in other languages.",
    ),
    ChatMessage.from_user("Tell me about {{location}}"),
]

response = pipe.run(
    data={
        "prompt_builder": {
            "template_variables": {"location": "Berlin"},
            "template": messages,
        },
    },
)

print(response["llm"]["replies"][0])

추적 백엔드를 직접 구성하기

OpenTelemetryConnector 대신 OpenTelemetryTracer를 활성화해서 OpenTelemetry 추적 백엔드를 직접 구성할 수 있어요. Haystack 컴포넌트를 임포트하기 전에 HAYSTACK_CONTENT_TRACING_ENABLED 환경 변수를 설정하고 TracerProvider를 구성하세요.

from opentelemetry import trace

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


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