SigNoz

SigNoz

LiteLLM 관측성 설정에 대한 자세한 내용은 SigNoz LiteLLM observability 문서를 확인하세요.

출처: 문서

본문

개요 (Overview)

이 가이드는 OpenTelemetry를 사용해 LiteLLM SDK와 Proxy Server의 관측성과 모니터링을 설정하고, 로그·트레이스·메트릭을 SigNoz로 내보내는 방법을 안내해요. 이 통합을 통해 다양한 모델의 성능을 관찰하고, 요청/응답 세부 정보를 캡처하며, 시스템 수준 메트릭을 SigNoz에서 추적할 수 있어요. 이를 통해 LiteLLM 애플리케이션의 지연 시간, 오류율, 사용량 추세를 실시간으로 파악할 수 있어요.

AI 애플리케이션에 텔레메트리를 사용해 LiteLLM을 계측하면 AI 워크플로 전반에 걸쳐 완전한 관측성을 확보하여, 버그 디버깅, 성능 최적화, 사용자 상호작용 이해가 더 쉬워져요. SigNoz를 사용하면 통합 대시보드에서 상관된 트레이스·로그·메트릭을 분석하고, 알림을 구성하며, 신뢰성과 응답성을 개선하기 위한 구체적인 인사이트를 얻을 수 있어요.

사전 준비 (Prerequisites)

  • 활성 수집 키(ingestion key)가 있는 SigNoz Cloud 계정
  • SigNoz Cloud로 텔레메트리 데이터를 보낼 인터넷 접속
  • LiteLLM SDK 또는 Proxy 통합
  • Python: Python 패키지 관리를 위한 uv 설치 및 (선택 사항이지만 권장) 의존성을 격리할 Python 가상 환경

LiteLLM 모니터링 (Monitoring LiteLLM)

LiteLLM은 두 가지 방식으로 모니터링할 수 있어요. LiteLLM SDK(파이썬 애플리케이션 코드에 직접 임베드되어 프로그래밍 방식으로 LLM을 호출) 또는 LiteLLM Proxy Server(인프라 전반의 LLM 요청을 관리·라우팅하는 중앙 게이트웨이 역할을 하는 독립 서버)를 사용하는 방식이에요.

LiteLLM SDK

LiteLLM SDK 애플리케이션 계측에 대한 자세한 내용은 여기를 클릭하세요.

노코드 (No Code, 권장)

노코드 자동 계측은 코드 변경을 최소화하면서 빠르게 설정할 수 있어 권장돼요. 표준 instrumentor 라이브러리를 사용하고, 애플리케이션 코드를 수정하지 않고 관측성을 구축하려 할 때 이상적이에요.

Step 1: Python 환경에 필요한 패키지를 설치해요.

uv add \
  opentelemetry-api \
  opentelemetry-distro \
  opentelemetry-exporter-otlp \
  httpx \
  opentelemetry-instrumentation-httpx \
  litellm

Step 2: 자동 계측 추가

opentelemetry-bootstrap --action=install

Step 3: LiteLLM SDK 애플리케이션 계측

litellm.callbacks = ["otel"]를 호출해 LiteLLM SDK 계측을 초기화해요:

from litellm import litellm
litellm.callbacks = ["otel"]

이 호출은 애플리케이션의 모든 LiteLLM SDK 호출에 대해 자동 추적(tracing), 로그, 메트릭 수집을 활성화해요.

📌 참고: 애플리케이션 계측을 올바르게 구성하려면 LiteLLM 관련 호출 전에 이 호출을 실행해야 해요.

Step 4: 예시 실행

from litellm import completion, litellm

litellm.callbacks = ["otel"]
response = completion(
  model="openai/gpt-5.6-terra",
  messages=[{ "content": "What is SigNoz","role": "user"}])
print(response)

📌 참고: LiteLLM은 다양한 모델 프로바이더를 지원해요. 이 예시에서는 OpenAI를 사용해요. 이 코드를 실행하기 전에 생성한 API 키로 OPENAI_API_KEY 환경 변수가 설정되어 있는지 확인하세요.

Step 5: 자동 계측으로 애플리케이션 실행

OTEL_RESOURCE_ATTRIBUTES="service.name=<service_name>" \
OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.<region>.signoz.cloud:443" \
OTEL_EXPORTER_OTLP_HEADERS="signoz-ingestion-key=<your_ingestion_key>" \
OTEL_EXPORTER_OTLP_PROTOCOL=grpc \
OTEL_TRACES_EXPORTER=otlp \
OTEL_METRICS_EXPORTER=otlp \
OTEL_LOGS_EXPORTER=otlp \
OTEL_PYTHON_LOG_CORRELATION=true \
OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true \
OTEL_PYTHON_DISABLED_INSTRUMENTATIONS=openai \
opentelemetry-instrument <your_run_command>

참고: OTLP gRPC는 grpcio가 필요해요. uv add "litellm[grpc]" (또는 grpcio)로 설치하세요.

📌 참고: 트레이싱을 위해 OpenAI instrumentor를 비활성화하려면 실행 명령에 OTEL_PYTHON_DISABLED_INSTRUMENTATIONS=openai를 사용해요. 이렇게 하면 LiteLLM의 네이티브 텔레메트리/계측과의 충돌을 피해, 텔레메트리가 LiteLLM의 내장 계측을 통해서만 캡처되도록 보장해요.

  • <service_name>은 서비스 이름
  • <region>을 SigNoz Cloud 영역에 맞게 설정
  • <your_ingestion_key>를 SigNoz 수집 키로 교체
  • <your_run_command>를 애플리케이션 실행 명령으로 교체. 예: python main.py

📌 참고: 셀프 호스팅 SigNoz를 사용하나요? 대부분의 단계는 동일해요. 이 가이드를 적용하려면 Cloud → Self-Hosted에 표시된 대로 엔드포인트를 업데이트하고 수집 키 헤더를 제거하세요.

코드 (Code)

코드 기반 계측은 텔레메트리 구성에 대한 세밀한 제어를 제공해요. 리소스 속성, 샘플링 전략을 커스터마이즈하거나 기존 관측성 인프라와 통합해야 할 때 이 방식을 사용해요.

Step 1: Python 환경에 필요한 패키지를 설치해요.

uv add \
  opentelemetry-api \
  opentelemetry-sdk \
  opentelemetry-exporter-otlp \
  opentelemetry-instrumentation-httpx \
  opentelemetry-instrumentation-system-metrics \
  litellm

Step 2: Python 애플리케이션에서 필요한 모듈을 가져와요.

트레이스:

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

로그:

from opentelemetry.sdk._logs import LoggerProvider, LoggingHandler
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter
from opentelemetry._logs import set_logger_provider
import logging

메트릭:

from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.exporter.otlp.proto.http.metric_exporter import OTLPMetricExporter
from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
from opentelemetry import metrics
from opentelemetry.instrumentation.system_metrics import SystemMetricsInstrumentor
from opentelemetry.instrumentation.httpx import HTTPXClientInstrumentor

Step 3: SigNoz Cloud로 트레이스를 직접 보내도록 OpenTelemetry Tracer Provider를 설정해요.

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

resource = Resource.create({"service.name": "<service_name>"})
provider = TracerProvider(resource=resource)
span_exporter = OTLPSpanExporter(
    endpoint= os.getenv("OTEL_EXPORTER_TRACES_ENDPOINT"),
    headers={"signoz-ingestion-key": os.getenv("SIGNOZ_INGESTION_KEY")},
)
processor = BatchSpanProcessor(span_exporter)
provider.add_span_processor(processor)
trace.set_tracer_provider(provider)
  • <service_name>은 서비스 이름
  • OTEL_EXPORTER_TRACES_ENDPOINT → 적절한 영역의 SigNoz Cloud 트레이스 엔드포인트: https://ingest.<region>.signoz.cloud:443/v1/traces
  • SIGNOZ_INGESTION_KEY → SigNoz 수집 키

📌 참고: 셀프 호스팅 SigNoz를 사용하나요? 대부분의 단계는 동일해요. 이 가이드를 적용하려면 Cloud → Self-Hosted에 표시된 대로 엔드포인트를 업데이트하고 수집 키 헤더를 제거하세요.

Step 4: 로그 설정

import logging
from opentelemetry.sdk.resources import Resource
from opentelemetry._logs import set_logger_provider
from opentelemetry.sdk._logs import LoggerProvider, LoggingHandler
from opentelemetry.sdk._logs.export import BatchLogRecordProcessor
from opentelemetry.exporter.otlp.proto.http._log_exporter import OTLPLogExporter
import os

resource = Resource.create({"service.name": "<service_name>"})
logger_provider = LoggerProvider(resource=resource)
set_logger_provider(logger_provider)
otlp_log_exporter = OTLPLogExporter(
    endpoint= os.getenv("OTEL_EXPORTER_LOGS_ENDPOINT"),
    headers={"signoz-ingestion-key": os.getenv("SIGNOZ_INGESTION_KEY")},
)
logger_provider.add_log_record_processor(
    BatchLogRecordProcessor(otlp_log_exporter))

# Attach OTel logging handler to root logger
handler = LoggingHandler(level=logging.INFO, logger_provider=logger_provider)
logging.basicConfig(level=logging.INFO, handlers=[handler])
logger = logging.getLogger(__name__)
  • <service_name>은 서비스 이름
  • OTEL_EXPORTER_LOGS_ENDPOINT → 적절한 영역의 SigNoz Cloud 엔드포인트: https://ingest.<region>.signoz.cloud:443/v1/logs
  • SIGNOZ_INGESTION_KEY → SigNoz 수집 키

📌 참고: 셀프 호스팅 SigNoz를 사용하나요? 대부분의 단계는 동일해요. 이 가이드를 적용하려면 Cloud → Self-Hosted에 표시된 대로 엔드포인트를 업데이트하고 수집 키 헤더를 제거하세요.

Step 5: 메트릭 설정

from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.metrics import MeterProvider
from opentelemetry.exporter.otlp.proto.http.metric_exporter import OTLPMetricExporter
from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader
from opentelemetry import metrics
from opentelemetry.instrumentation.system_metrics import SystemMetricsInstrumentor
import os

resource = Resource.create({"service.name": "<service-name>"})
metric_exporter = OTLPMetricExporter(
    endpoint= os.getenv("OTEL_EXPORTER_METRICS_ENDPOINT"),
    headers={"signoz-ingestion-key": os.getenv("SIGNOZ_INGESTION_KEY")},
)
reader = PeriodicExportingMetricReader(metric_exporter)
metric_provider = MeterProvider(metric_readers=[reader], resource=resource)
metrics.set_meter_provider(metric_provider)

meter = metrics.get_meter(__name__)

# turn on out-of-the-box metrics
SystemMetricsInstrumentor().instrument()
HTTPXClientInstrumentor().instrument()
  • <service_name>은 서비스 이름
  • OTEL_EXPORTER_METRICS_ENDPOINT → 적절한 영역의 SigNoz Cloud 엔드포인트: https://ingest.<region>.signoz.cloud:443/v1/metrics
  • SIGNOZ_INGESTION_KEY → SigNoz 수집 키

📌 참고: 셀프 호스팅 SigNoz를 사용하나요? 대부분의 단계는 동일해요. 이 가이드를 적용하려면 Cloud → Self-Hosted에 표시된 대로 엔드포인트를 업데이트하고 수집 키 헤더를 제거하세요.

📌 참고: SystemMetricsInstrumentor는 시스템 메트릭(CPU, 메모리 등)을 제공하고, HTTPXClientInstrumentor는 요청 지속 시간 같은 아웃바운드 HTTP 요청 메트릭을 제공해요. LiteLLM 애플리케이션에 커스텀 메트릭을 추가하려면 Python Custom Metrics를 참조하세요.

Step 6: LiteLLM 애플리케이션 계측

litellm.callbacks = ["otel"]를 호출해 LiteLLM SDK 계측을 초기화해요:

from litellm import litellm
litellm.callbacks = ["otel"]

이 호출은 애플리케이션의 모든 LiteLLM SDK 호출에 대해 자동 추적, 로그, 메트릭 수집을 활성화해요.

📌 참고: 애플리케이션 계측을 올바르게 구성하려면 LiteLLM 관련 호출 전에 이 호출을 실행해야 해요.

Step 7: 예시 실행

from litellm import completion, litellm

litellm.callbacks = ["otel"]
response = completion(
  model="openai/gpt-5.6-terra",
  messages=[{ "content": "What is SigNoz","role": "user"}])
print(response)

📌 참고: LiteLLM은 다양한 모델 프로바이더를 지원해요. 이 예시에서는 OpenAI를 사용해요. 이 코드를 실행하기 전에 생성한 API 키로 OPENAI_API_KEY 환경 변수가 설정되어 있는지 확인하세요.

SigNoz에서 트레이스·로그·메트릭 보기 (View Traces, Logs, and Metrics in SigNoz)

LiteLLM 명령은 이제 자동으로 트레이스, 로그, 메트릭을 생성할 거예요.

  • 트레이스: SigNoz Cloud의 traces 탭에서 트레이스를 확인할 수 있어요. SigNoz에서 트레이스를 클릭하면 모든 관련 스팬과 그 이벤트·속성을 포함한 상세 뷰를 볼 수 있어요.
  • 로그: SigNoz Cloud의 logs 탭에서 로그를 확인할 수 있어요. 트레이스 뷰의 "Related Logs" 버튼을 클릭해 상관된 로그를 볼 수도 있어요. SigNoz에서 로그를 클릭하면 속성을 포함한 상세 뷰를 볼 수 있어요.
  • 메트릭: SigNoz Cloud의 metrics 탭에서 LiteLLM 관련 메트릭을 확인할 수 있어요. 메트릭을 클릭하면 속성을 포함한 상세 뷰를 볼 수 있어요.

대시보드 (Dashboard)

애플리케이션의 LiteLLM 사용량 모니터링을 위한 특수 시각화를 제공하는 커스텀 LiteLLM SDK 대시보드 여기에서 확인할 수 있어요. 대시보드에는 LLM 사용량에 특화된 사전 구축 차트와 빠르게 시작할 수 있는 가져오기 지침이 포함돼 있어요.

LiteLLM Proxy Server

Step 1: Python 환경에 필요한 패키지를 설치해요.

uv add opentelemetry-api \
  opentelemetry-sdk \
  opentelemetry-exporter-otlp \
  'litellm[proxy]'

Step 2: LiteLLM Proxy Server용 otel 구성

다음을 config.yaml에 추가해요:

litellm_settings:
  callbacks: ['otel']

Step 3: 다음 환경 변수를 설정해요:

export OTEL_EXPORTER_OTLP_ENDPOINT="https://ingest.<region>.signoz.cloud:443"
export OTEL_EXPORTER_OTLP_HEADERS="signoz-ingestion-key=<your_ingestion_key>"
export OTEL_EXPORTER_OTLP_PROTOCOL="grpc"
export OTEL_TRACES_EXPORTER="otlp"
export OTEL_METRICS_EXPORTER="otlp"
export OTEL_LOGS_EXPORTER="otlp"

참고: OTLP gRPC는 grpcio가 필요해요. uv add "litellm[grpc]" (또는 grpcio)로 설치하세요.

  • <region>을 SigNoz Cloud 영역에 맞게 설정
  • <your_ingestion_key>를 SigNoz 수집 키로 교체

📌 참고: 셀프 호스팅 SigNoz를 사용하나요? 대부분의 단계는 동일해요. 이 가이드를 적용하려면 Cloud → Self-Hosted에 표시된 대로 엔드포인트를 업데이트하고 수집 키 헤더를 제거하세요.

Step 4: 구성 파일을 사용해 프록시 서버를 실행해요:

litellm --config config.yaml

이제 LiteLLM 프록시 서버를 통해 이루어지는 모든 호출이 추적되어 SigNoz로 전송돼요.

SigNoz Cloud의 traces 탭에서 트레이스를 확인할 수 있어요. SigNoz에서 트레이스를 클릭하면 모든 관련 스팬과 그 이벤트·속성을 포함한 상세 뷰를 볼 수 있어요.

대시보드 (Dashboard)

애플리케이션의 LiteLLM Proxy 사용량 모니터링을 위한 특수 시각화를 제공하는 커스텀 LiteLLM Proxy 대시보드 여기에서 확인할 수 있어요. 대시보드에는 LLM 사용량에 특화된 사전 구축 차트와 빠르게 시작할 수 있는 가져오기 지침이 포함돼 있어요.

더 알아보기 (Learn more)