OpenTelemetry로 추적하기

​

LangChain 애플리케이션 추적하기

1. OpenTelemetry 지원이 포함된 LangSmith 패키지를 설치합니다:
   pip

   Copy

   pip install "langsmith[otel]"
   pip install langchain
   

   Python SDK 버전 langsmith>=0.3.18이 필요합니다. 중요한 OpenTelemetry 수정 사항의 혜택을 받으려면 langsmith>=0.4.25를 권장합니다.
2. LangChain/LangGraph 앱에서 LANGSMITH_OTEL_ENABLED 환경 변수를 설정하여 OpenTelemetry 통합을 활성화합니다:
   Shell

   Copy

   LANGSMITH_OTEL_ENABLED=true
   LANGSMITH_TRACING=true
   LANGSMITH_ENDPOINT=https://api.smith.langchain.com
   LANGSMITH_API_KEY=<your_langsmith_api_key>
   # 여러 워크스페이스에 연결된 LangSmith API 키의 경우, LANGSMITH_WORKSPACE_ID 환경 변수를 설정하여 사용할 워크스페이스를 지정하세요.
   

3. 추적 기능이 포함된 LangChain 애플리케이션을 생성합니다. 예시:
   Copy

   import os
   from langchain_openai import ChatOpenAI
   from langchain_core.prompts import ChatPromptTemplate
   
   # 체인 생성
   prompt = ChatPromptTemplate.from_template("Tell me a joke about {topic}")
   model = ChatOpenAI()
   chain = prompt | model
   
   # 체인 실행
   result = chain.invoke({"topic": "programming"})
   print(result.content)
   

4. 애플리케이션이 실행되면 LangSmith 대시보드에서 추적 정보를 확인할 수 있습니다 (예시).

​

LangChain이 아닌 애플리케이션 추적하기

1. OpenTelemetry SDK, OpenTelemetry exporter 패키지 및 OpenAI 패키지를 설치합니다:
   pip

   Copy

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

2. 엔드포인트에 대한 환경 변수를 설정하고, 특정 값으로 대체합니다:
   Shell

   Copy

   OTEL_EXPORTER_OTLP_ENDPOINT=https://api.smith.langchain.com/otel
   OTEL_EXPORTER_OTLP_HEADERS="x-api-key=<your langsmith api key>"
   

   otel exporter의 설정 방식에 따라, 추적 데이터만 전송하는 경우 엔드포인트에 /v1/traces를 추가해야 할 수 있습니다.
   LangSmith를 셀프 호스팅하는 경우, 기본 엔드포인트를 LangSmith API 엔드포인트로 교체하고 /api/v1을 추가하세요. 예시: OTEL_EXPORTER_OTLP_ENDPOINT=https://ai-company.com/api/v1/otel
   선택사항: “default”가 아닌 커스텀 프로젝트 이름을 지정합니다:
   Shell

   Copy

   OTEL_EXPORTER_OTLP_ENDPOINT=https://api.smith.langchain.com/otel
   OTEL_EXPORTER_OTLP_HEADERS="x-api-key=<your langsmith api key>,Langsmith-Project=<project name>"
   

3. 추적을 기록합니다. 이 코드는 LangSmith로 추적 데이터를 전송하는 OTEL tracer와 exporter를 설정합니다. 그런 다음 OpenAI를 호출하고 필요한 OpenTelemetry 속성을 전송합니다.
   Copy

   from openai import OpenAI
   from opentelemetry import trace
   from opentelemetry.sdk.trace import TracerProvider
   from opentelemetry.sdk.trace.export import (
       BatchSpanProcessor,
   )
   from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
   
   client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))
   
   otlp_exporter = OTLPSpanExporter(
       timeout=10,
   )
   
   trace.set_tracer_provider(TracerProvider())
   trace.get_tracer_provider().add_span_processor(
       BatchSpanProcessor(otlp_exporter)
   )
   
   tracer = trace.get_tracer(__name__)
   
   def call_openai():
       model = "gpt-4o-mini"
       with tracer.start_as_current_span("call_open_ai") as span:
           span.set_attribute("langsmith.span.kind", "LLM")
           span.set_attribute("langsmith.metadata.user_id", "user_123")
           span.set_attribute("gen_ai.system", "OpenAI")
           span.set_attribute("gen_ai.request.model", model)
           span.set_attribute("llm.request.type", "chat")
   
           messages = [
               {"role": "system", "content": "You are a helpful assistant."},
               {
                   "role": "user",
                   "content": "Write a haiku about recursion in programming."
               }
           ]
   
           for i, message in enumerate(messages):
               span.set_attribute(f"gen_ai.prompt.{i}.content", str(message["content"]))
               span.set_attribute(f"gen_ai.prompt.{i}.role", str(message["role"]))
   
           completion = client.chat.completions.create(
               model=model,
               messages=messages
           )
   
           span.set_attribute("gen_ai.response.model", completion.model)
           span.set_attribute("gen_ai.completion.0.content", str(completion.choices[0].message.content))
           span.set_attribute("gen_ai.completion.0.role", "assistant")
           span.set_attribute("gen_ai.usage.prompt_tokens", completion.usage.prompt_tokens)
           span.set_attribute("gen_ai.usage.completion_tokens", completion.usage.completion_tokens)
           span.set_attribute("gen_ai.usage.total_tokens", completion.usage.total_tokens)
   
           return completion.choices[0].message
   
   if __name__ == "__main__":
       call_openai()
   

4. LangSmith 대시보드에서 추적 정보를 확인합니다 (예시).

​

대체 제공자로 추적 데이터 전송하기

​

전역 구성을 위한 환경 변수 사용

OTEL_EXPORTER_OTLP_ENDPOINT: 엔드포인트 URL 재정의
OTEL_EXPORTER_OTLP_HEADERS: 커스텀 헤더 추가 (LangSmith API 키와 프로젝트는 자동으로 추가됨)
OTEL_SERVICE_NAME: 커스텀 서비스 이름 설정 (기본값: "langsmith")

1. 위에 표시된 대로 OTEL 환경 변수를 설정하거나,
2. LangChain 컴포넌트를 초기화하기 전에 전역 trace provider를 설정합니다. LangSmith는 이를 감지하고 자체 제공자를 생성하는 대신 이를 사용합니다.

​

대체 OTLP 엔드포인트 구성

import os
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate

# LangChain을 위한 환경 변수 설정
os.environ["LANGSMITH_OTEL_ENABLED"] = "true"
os.environ["LANGSMITH_TRACING"] = "true"

# 커스텀 엔드포인트를 위한 OTLP exporter 구성
provider = TracerProvider()
otlp_exporter = OTLPSpanExporter(
    # 제공자의 엔드포인트로 변경
    endpoint="https://otel.your-provider.com/v1/traces",
    # 인증에 필요한 헤더 추가
    headers={"api-key": "your-api-key"}
)
processor = BatchSpanProcessor(otlp_exporter)
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)

# LangChain 애플리케이션 생성 및 실행
prompt = ChatPromptTemplate.from_template("Tell me a joke about {topic}")
model = ChatOpenAI()
chain = prompt | model
result = chain.invoke({"topic": "programming"})
print(result.content)

​

지원되는 OpenTelemetry 속성 및 이벤트 매핑

​

핵심 LangSmith 속성

​

GenAI 표준 속성

​

GenAI 요청 매개변수

​

GenAI 사용량 메트릭

​

TraceLoop 속성

​

OpenInference 속성

​

LLM 속성

​

프롬프트 템플릿 속성

​

Retriever 속성

​

도구 속성

​

Logfire 속성

​

OpenTelemetry 이벤트 매핑

​

이벤트 속성 추출

• content → 메시지 콘텐츠
• role → 메시지 역할
• id → tool_call_id (도구 메시지의 경우)
• gen_ai.event.content → 전체 메시지 JSON

• finish_reason → 선택 완료 이유
• message.content → 선택 메시지 콘텐츠
• message.role → 선택 메시지 역할
• tool_calls.{n}.id → 도구 호출 ID
• tool_calls.{n}.function.name → 도구 함수 이름
• tool_calls.{n}.function.arguments → 도구 함수 인자
• tool_calls.{n}.type → 도구 호출 타입

• exception.message → 오류 메시지
• exception.stacktrace → 오류 스택트레이스 (메시지에 추가됨)

​

구현 예시

​

LangSmith SDK를 사용한 추적

import asyncio
from langsmith.integrations.otel import configure
from google.adk import Runner
from google.adk.agents import LlmAgent
from google.adk.sessions import InMemorySessionService
from google.genai import types

# LangSmith OpenTelemetry 내보내기 구성 (OTEL 환경 변수나 헤더 불필요)
configure(project_name="adk-otel-demo")


async def main():
    agent = LlmAgent(
        name="travel_assistant",
        model="gemini-2.5-flash-lite",
        instruction="You are a helpful travel assistant.",
    )

    session_service = InMemorySessionService()
    runner = Runner(app_name="travel_app", agent=agent, session_service=session_service)

    user_id = "user_123"
    session_id = "session_abc"
    await session_service.create_session(app_name="travel_app", user_id=user_id, session_id=session_id)

    new_message = types.Content(parts=[types.Part(text="Hi! Recommend a weekend trip to Paris.")], role="user")

    for event in runner.run(user_id=user_id, session_id=session_id, new_message=new_message):
        print(event)


if __name__ == "__main__":
    asyncio.run(main())

5. LangSmith 대시보드에서 추적 정보를 확인합니다 (예시).

​

고급 구성

​

팬아웃을 위한 OpenTelemetry Collector 사용

1. 환경에 맞는 OpenTelemetry Collector를 설치합니다.
2. 여러 대상으로 내보내는 구성 파일(예: otel-collector-config.yaml)을 생성합니다:
   Copy

   receivers:
     otlp:
       protocols:
         grpc:
           endpoint: 0.0.0.0:4317
         http:
           endpoint: 0.0.0.0:4318
   
   processors:
     batch:
   
   exporters:
     otlphttp/langsmith:
       endpoint: https://api.smith.langchain.com/otel/v1/traces
       headers:
         x-api-key: ${env:LANGSMITH_API_KEY}
         Langsmith-Project: my_project
     otlphttp/other_provider:
       endpoint: https://otel.your-provider.com/v1/traces
       headers:
         api-key: ${env:OTHER_PROVIDER_API_KEY}
   
   service:
     pipelines:
       traces:
         receivers: [otlp]
         processors: [batch]
         exporters: [otlphttp/langsmith, otlphttp/other_provider]
   

3. Collector로 전송하도록 애플리케이션을 구성합니다:
   Copy

   import os
   from opentelemetry import trace
   from opentelemetry.sdk.trace import TracerProvider
   from opentelemetry.sdk.trace.export import BatchSpanProcessor
   from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
   from langchain_openai import ChatOpenAI
   from langchain_core.prompts import ChatPromptTemplate
   
   # 로컬 OpenTelemetry Collector를 가리킴
   otlp_exporter = OTLPSpanExporter(
       endpoint="http://localhost:4318/v1/traces"
   )
   provider = TracerProvider()
   processor = BatchSpanProcessor(otlp_exporter)
   provider.add_span_processor(processor)
   trace.set_tracer_provider(provider)
   
   # LangChain을 위한 환경 변수 설정
   os.environ["LANGSMITH_OTEL_ENABLED"] = "true"
   os.environ["LANGSMITH_TRACING"] = "true"
   
   # LangChain 애플리케이션 생성 및 실행
   prompt = ChatPromptTemplate.from_template("Tell me a joke about {topic}")
   model = ChatOpenAI()
   chain = prompt | model
   result = chain.invoke({"topic": "programming"})
   print(result.content)
   

• 모든 텔레메트리 대상에 대한 중앙 집중식 구성
• 애플리케이션 코드의 오버헤드 감소
• 더 나은 확장성과 복원력
• 애플리케이션 코드를 변경하지 않고 대상을 추가하거나 제거할 수 있는 기능

​

LangChain과 OpenTelemetry를 사용한 분산 추적

​

분산 추적에서의 컨텍스트 전파

• Trace ID: 전체 추적에 대한 고유 식별자
• Span ID: 현재 span에 대한 고유 식별자
• 샘플링 결정: 이 추적을 샘플링해야 하는지 여부를 나타냄

​

LangChain으로 분산 추적 설정

import os
from opentelemetry import trace
from opentelemetry.propagate import inject, extract
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
import requests
from langchain_openai import ChatOpenAI
from langchain_core.prompts import ChatPromptTemplate

# OpenTelemetry trace provider 설정
provider = TracerProvider()
otlp_exporter = OTLPSpanExporter(
    endpoint="https://api.smith.langchain.com/otel/v1/traces",
    headers={"x-api-key": os.getenv("LANGSMITH_API_KEY"), "Langsmith-Project": "my_project"}
)
processor = BatchSpanProcessor(otlp_exporter)
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)
tracer = trace.get_tracer(__name__)

# 서비스 A: span을 생성하고 컨텍스트를 서비스 B로 전파
def service_a():
    with tracer.start_as_current_span("service_a_operation") as span:
        # 체인 생성
        prompt = ChatPromptTemplate.from_template("Summarize: {text}")
        model = ChatOpenAI()
        chain = prompt | model

        # 체인 실행
        result = chain.invoke({"text": "OpenTelemetry is an observability framework"})

        # 서비스 B로 컨텍스트 전파
        headers = {}
        inject(headers)  # 헤더에 추적 컨텍스트를 주입

        # 추적 컨텍스트와 함께 서비스 B 호출
        response = requests.post(
            "http://service-b.example.com/process",
            headers=headers,
            json={"summary": result.content}
        )
        return response.json()

# 서비스 B: 컨텍스트를 추출하고 추적을 계속
from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route("/process", methods=["POST"])
def service_b_endpoint():
    # 요청 헤더에서 추적 컨텍스트를 추출
    context = extract(request.headers)
    with tracer.start_as_current_span("service_b_operation", context=context) as span:
        data = request.json
        summary = data.get("summary", "")

        # 다른 LLM 체인으로 요약 처리
        prompt = ChatPromptTemplate.from_template("Analyze the sentiment of: {text}")
        model = ChatOpenAI()
        chain = prompt | model
        result = chain.invoke({"text": summary})

        return jsonify({"analysis": result.content})

if __name__ == "__main__":
    app.run(port=5000)