LiteLLM可观测性：日志、监控与追踪集成

【免费下载链接】litellm Call all LLM APIs using the OpenAI format. Use Bedrock, Azure, OpenAI, Cohere, Anthropic, Ollama, Sagemaker, HuggingFace, Replicate (100+ LLMs) 项目地址: https://gitcode.com/GitHub_Trending/li/litellm

LiteLLM提供了一个全面的可观测性解决方案，包括内置日志系统、回调机制以及与主流第三方监控平台的深度集成。该系统支持标准日志输出和结构化JSON日志，提供丰富的回调接口，能够无缝集成MLflow、Langfuse、Prometheus和OpenTelemetry等平台。通过灵活的配置和性能优化特性，LiteLLM为开发者提供了从简单调试到复杂生产环境监控的完整支持。

内置日志系统与回调机制

LiteLLM提供了一个强大而灵活的内置日志系统和回调机制，使开发者能够轻松地监控、追踪和分析LLM API调用。这套系统不仅支持标准的日志输出，还提供了丰富的回调接口，可以与各种第三方监控和可观测性平台无缝集成。

核心日志架构

LiteLLM的日志系统基于Python的标准logging模块构建，但进行了深度定制以支持LLM特有的日志需求。系统包含三个主要的日志记录器：

# LiteLLM核心日志记录器
verbose_logger = logging.getLogger("LiteLLM")
verbose_router_logger = logging.getLogger("LiteLLM Router") 
verbose_proxy_logger = logging.getLogger("LiteLLM Proxy")

每个记录器都配置了专门的处理器和格式化器，支持JSON格式和结构化日志输出：

回调机制详解

LiteLLM的回调系统支持多种事件类型的处理，包括：

• 成功回调：当API调用成功完成时触发
• 失败回调：当API调用失败时触发
• 流式回调：处理流式响应时的实时回调
• 预调用回调：在API调用前执行的预处理

回调配置示例

from litellm import completion
import os

# 配置环境变量用于日志工具
os.environ["OPENAI_API_KEY"] = "your-openai-key"
os.environ["LUNARY_PUBLIC_KEY"] = "your-lunary-public-key"
os.environ["HELICONE_API_KEY"] = "your-helicone-auth-key"

# 设置成功回调列表
litellm.success_callback = ["lunary", "mlflow", "langfuse", "athina", "helicone"]

# API调用将自动记录到所有配置的回调服务
response = completion(
    model="openai/gpt-4o", 
    messages=[{"role": "user", "content": "Hi 👋 - i'm openai"}]
)

动态回调参数系统

LiteLLM引入了动态回调参数机制，允许在每个请求级别动态配置回调参数：

# 动态回调参数配置
dynamic_params = {
    "langfuse_public_key": "dynamic-public-key",
    "langfuse_secret": "dynamic-secret-key",
    "langfuse_host": "https://your-langfuse-instance.com"
}

response = completion(
    model="openai/gpt-4o",
    messages=messages,
    standard_callback_dynamic_params=dynamic_params
)

内置回调处理器

LiteLLM内置了丰富的回调处理器，支持与主流可观测性平台的集成：

回调处理器	功能描述	配置方式
MLflow	实验追踪和模型管理	自动检测环境变量
Langfuse	LLM应用可观测性	设置LANGFUSE环境变量
Lunary	提示管理和分析	设置LUNARY环境变量
Helicone	LLM代理和缓存	设置HELICONE环境变量
Prometheus	指标监控	自动集成
OpenTelemetry	分布式追踪	配置OTEL环境变量

自定义回调开发

开发者可以轻松创建自定义回调处理器：

from litellm.integrations.custom_logger import CustomLogger

class MyCustomLogger(CustomLogger):
    def __init__(self):
        super().__init__()
    
    async def async_log_success_event(self, kwargs, response_obj, start_time, end_time):
        """处理成功的API调用"""
        logging_data = {
            "model": kwargs.get("model"),
            "messages": kwargs.get("messages"),
            "response": response_obj,
            "latency": end_time - start_time,
            "timestamp": datetime.now().isoformat()
        }
        # 自定义处理逻辑
        await self._send_to_custom_service(logging_data)
    
    def log_failure_event(self, kwargs, response_obj, start_time, end_time):
        """处理失败的API调用"""
        error_data = {
            "error": str(response_obj) if isinstance(response_obj, Exception) else "Unknown error",
            "request": kwargs,
            "timestamp": datetime.now().isoformat()
        }
        # 自定义错误处理逻辑
        self._log_error(error_data)

# 注册自定义回调
litellm.success_callback.append(MyCustomLogger())

日志级别控制

LiteLLM支持细粒度的日志级别控制：

# 设置日志级别
export LITELLM_LOG="DEBUG"  # DEBUG, INFO, WARNING, ERROR

# 启用JSON日志格式
export JSON_LOGS="true"

# 特定组件的日志控制
export LITELLM_PROXY_LOG="INFO"
export LITELLM_ROUTER_LOG="DEBUG"

性能优化特性

日志系统包含多项性能优化措施：

• 异步处理：所有回调操作默认异步执行，不影响主请求性能
• 批量处理：支持批量发送日志数据，减少网络开销
• 缓存机制：频繁使用的配置信息进行缓存，提高响应速度
• 错误隔离：单个回调失败不会影响其他回调的正常执行

监控指标收集

系统自动收集丰富的监控指标：

指标类型	描述	示例
延迟指标	API调用耗时分布	P50, P90, P99延迟
成功率	请求成功比例	成功率百分比
令牌使用	输入输出令牌统计	总令牌数、成本估算
错误率	各类错误发生频率	按错误类型分类

通过这套内置的日志系统和回调机制，LiteLLM为开发者提供了完整的可观测性解决方案，无论是简单的调试需求还是复杂的生产环境监控，都能得到充分的支持。

MLflow、Langfuse等第三方集成

在现代LLM应用开发中，可观测性已成为确保系统稳定性和性能的关键要素。LiteLLM提供了与多种第三方可观测性平台的深度集成，包括MLflow、Langfuse等，使开发者能够轻松实现LLM调用的追踪、监控和日志记录。

MLflow集成

MLflow是一个开源的机器学习生命周期管理平台，LiteLLM通过MlflowLogger类实现了与MLflow Tracing功能的深度集成。该集成能够自动记录LLM调用的详细信息，包括输入输出、耗时、token使用量等关键指标。

核心功能特性

LiteLLM的MLflow集成提供了以下核心功能：

• 自动Span创建：为每个LLM调用自动创建MLflow span，支持嵌套span结构
• 流式响应处理：专门处理流式响应，将多个chunk聚合为单个span
• 丰富的元数据记录：记录模型信息、API基础URL、缓存命中状态等
• 错误追踪：自动记录异常信息，包括完整的错误堆栈

配置与使用

启用MLflow集成非常简单，只需设置相应的回调函数：

import litellm
from litellm import completion

# 设置MLflow为成功回调
litellm.success_callback = ["mlflow"]

# 进行LLM调用，数据将自动发送到MLflow
response = completion(
    model="gpt-3.5-turbo",
    messages=[{"role": "user", "content": "Hello, how are you?"}]
)

数据结构示例

MLflow span中记录的数据结构如下：

高级配置选项

对于需要更精细控制的场景，可以创建自定义的MLflow记录器实例：

from litellm.integrations.mlflow import MlflowLogger

# 创建自定义MLflow记录器
mlflow_logger = MlflowLogger()

# 设置自定义回调
litellm.success_callback = [mlflow_logger.log_success_event]
litellm.failure_callback = [mlflow_logger.log_failure_event]

Langfuse集成

Langfuse是专为LLM应用设计的可观测性平台，LiteLLM提供了完整的Langfuse集成支持，包括trace记录、prompt管理和成本追踪等功能。

环境配置

要启用Langfuse集成，需要设置相应的环境变量：

import os

# 设置Langfuse认证信息
os.environ["LANGFUSE_PUBLIC_KEY"] = "your-public-key"
os.environ["LANGFUSE_SECRET_KEY"] = "your-secret-key"
os.environ["LANGFUSE_HOST"] = "https://cloud.langfuse.com"

# 启用Langfuse回调
litellm.success_callback = ["langfuse"]

功能特性表

下表展示了LiteLLM与Langfuse集成的主要功能特性：

功能类别	具体特性	支持情况
Trace记录	完整的请求响应追踪	✅ 完全支持
	流式响应处理	✅ 完全支持
	多模型调用链	✅ 完全支持
元数据记录	Token使用统计	✅ 完全支持
	成本计算	✅ 完全支持
	缓存命中状态	✅ 完全支持
Prompt管理	Prompt版本控制	✅ 完全支持
	变量替换追踪	✅ 完全支持
	A/B测试支持	✅ 完全支持

动态配置支持

LiteLLM支持在请求级别动态配置Langfuse参数：

response = completion(
    model="gpt-4",
    messages=[{"role": "user", "content": "Explain quantum computing"}],
    metadata={
        "langfuse": {
            "trace_id": "custom-trace-123",
            "session_id": "user-session-456",
            "release": "v1.2.3",
            "tags": ["production", "important"]
        }
    }
)

数据处理流程

LiteLLM与Langfuse的数据处理流程如下：

集成最佳实践

1. 多平台并行记录

对于关键业务场景，建议同时使用多个可观测性平台：

# 同时启用MLflow和Langfuse
litellm.success_callback = ["mlflow", "langfuse", "athina"]

2. 环境特定的配置

根据运行环境调整配置：

import os

# 根据环境设置不同的配置
if os.getenv("ENVIRONMENT") == "production":
    litellm.success_callback = ["mlflow", "langfuse"]
    litellm.failure_callback = ["mlflow", "langfuse", "slack"]
elif os.getenv("ENVIRONMENT") == "development":
    litellm.success_callback = ["mlflow"]

3. 自定义数据处理

对于特殊需求，可以创建自定义处理逻辑：

from litellm.integrations.custom_logger import CustomLogger

class CustomObservabilityLogger(CustomLogger):
    def log_success_event(self, kwargs, response_obj, start_time, end_time):
        # 自定义成功事件处理逻辑
        super().log_success_event(kwargs, response_obj, start_time, end_time)
        
        # 额外的自定义逻辑
        self._send_to_custom_analytics(kwargs, response_obj)

# 使用自定义记录器
custom_logger = CustomObservabilityLogger()
litellm.success_callback = [custom_logger.log_success_event]

性能考量

在使用第三方集成时，需要注意以下性能考量：

1. 异步处理：LiteLLM的所有回调都是异步执行的，不会阻塞主请求流程
2. 批量处理：支持批量发送日志数据，减少网络开销
3. 错误恢复：集成组件具有错误恢复机制，网络问题不会影响主功能
4. 资源控制：可配置的刷新间隔和批量大小，控制资源使用

通过合理的配置和使用，LiteLLM的第三方集成能够为LLM应用提供强大的可观测性能力，同时保持优秀的性能表现。

Prometheus监控指标导出

在现代LLM应用的可观测性体系中，Prometheus作为云原生监控的事实标准，为LiteLLM提供了强大的指标收集和暴露能力。通过Prometheus监控指标导出，您可以实时追踪LLM API调用的性能、错误率和资源使用情况，为系统优化和故障排查提供数据支撑。

核心监控指标

LiteLLM通过Prometheus Services Logger组件暴露了丰富的监控指标，主要包括三大类：

指标类型	指标名称格式	描述	标签
Histogram	litellm_{service}_latency	服务调用延迟分布	service
Counter	litellm_{service}_total_requests	总请求数量统计	service
Counter	litellm_{service}_failed_requests	失败请求数量统计	service, error_class, function_name
Gauge	litellm_{service}_size	服务资源使用量	service

其中{service}支持以下服务类型：

• litellm: LiteLLM核心服务
• redis: Redis缓存服务
• postgres: PostgreSQL数据库
• llm: 各大LLM提供商API

配置与启用

要启用Prometheus监控，需要在LiteLLM配置中添加prometheus_system回调：

import litellm

# 启用Prometheus监控
litellm.service_callback = ["prometheus_system"]

# 或者与其他监控工具同时使用
litellm.service_callback = ["prometheus_system", "datadog", "otel"]

指标收集原理

LiteLLM通过异步钩子机制收集指标数据：

延迟桶配置

LiteLLM使用预定义的延迟桶来统计延迟分布：

# 默认延迟桶配置（秒）
LATENCY_BUCKETS = [
    0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 
    0.75, 1.0, 2.5, 5.0, 7.5, 10.0, 15.0, 20.0, 30.0
]

实战示例

1. 监控LLM API调用延迟

from litellm import completion
import time

# 模拟LLM调用并监控延迟
start_time = time.time()
try:
    response = completion(
        model="gpt-3.5-turbo",
        messages=[{"role": "user", "content": "Hello!"}]
    )
    end_time = time.time()
    duration = end_time - start_time
    
    # 延迟指标会自动记录到Prometheus
    print(f"调用成功，耗时: {duration:.3f}s")
except Exception as e:
    # 错误指标也会自动记录
    print(f"调用失败: {str(e)}")

2. 自定义服务监控

from litellm._service_logger import ServiceLogging

service_logger = ServiceLogging()

# 监控自定义服务
async def monitor_custom_service():
    start_time = time.time()
    try:
        # 执行自定义服务逻辑
        result = await custom_service_call()
        duration = time.time() - start_time
        
        # 记录成功指标
        await service_logger.async_service_success_hook(
            service="custom_service",
            call_type="process_data",
            duration=duration
        )
        return result
    except Exception as e:
        # 记录失败指标
        await service_logger.async_service_failure_hook(
            service="custom_service", 
            duration=time.time() - start_time,
            error=e,
            call_type="process_data"
        )
        raise e

3. Prometheus查询示例

启用监控后，您可以使用以下PromQL查询来监控系统状态：

# 查询LLM服务每分钟请求率
rate(litellm_llm_total_requests[1m])

# 查询错误率
rate(litellm_llm_failed_requests[1m]) / rate(litellm_llm_total_requests[1m])

# 查询P95延迟
histogram_quantile(0.95, rate(litellm_llm_latency_bucket[5m]))

# 查询各服务的当前请求量
litellm_llm_total_requests

高级配置

自定义指标标签

您可以通过event_metadata参数添加自定义标签：

await service_logger.async_service_success_hook(
    service="llm",
    call_type="completion",
    duration=2.5,
    event_metadata={
        "model": "gpt-4",
        "region": "us-west-1",
        "user_id": "user_123"
    }
)

Docker Compose部署

使用Docker部署时，需要配置Prometheus抓取目标：

# docker-compose.yml
version: '3.8'
services:
  litellm:
    image: ghcr.io/berriai/litellm:main
    ports:
      - "4000:4000"
    environment:
      - LITELLM_SERVICE_CALLBACK=prometheus_system

  prometheus:
    image: prom/prometheus
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
    depends_on:
      - litellm

对应的Prometheus配置：

# prometheus.yml
global:
  scrape_interval: 15s

scrape_configs:
  - job_name: 'litellm'
    static_configs:
      - targets: ['litellm:4000']
    metrics_path: /metrics

监控看板配置

基于收集的指标，您可以配置Grafana看板来可视化监控数据：

{
  "panels": [
    {
      "title": "LLM API请求率",
      "type": "graph",
      "targets": [{
        "expr": "rate(litellm_llm_total_requests[1m])",
        "legendFormat": "{{service}}"
      }]
    },
    {
      "title": "错误率",
      "type": "stat",
      "targets": [{
        "expr": "rate(litellm_llm_failed_requests[1m]) / rate(litellm_llm_total_requests[1m])",
        "format": "percent"
      }]
    }
  ]
}

故障排查

当监控指标显示异常时，可以通过以下步骤进行排查：

1. 高延迟问题：检查litellm_llm_latency指标，识别慢请求模式
2. 高错误率：查看litellm_llm_failed_requests的错误分类标签
3. 服务不可用：检查Redis/PostgreSQL连接指标
4. 资源瓶颈：监控Gauge类型的资源使用指标

通过Prometheus监控指标导出，LiteLLM为LLM应用提供了生产级别的可观测性保障，帮助您构建稳定、高性能的AI应用系统。

OpenTelemetry分布式追踪

在现代LLM应用架构中，分布式追踪是确保系统可观测性的关键组件。LiteLLM通过OpenTelemetry集成提供了强大的分布式追踪能力，使开发者和运维团队能够深入了解LLM请求的完整生命周期，从用户请求到模型响应，再到下游依赖服务的调用。

核心架构设计

LiteLLM的OpenTelemetry集成采用了模块化设计，支持多种导出器和配置方式。系统架构遵循OpenTelemetry标准，提供了完整的追踪链路：

配置与初始化

OpenTelemetry在LiteLLM中的配置非常灵活，支持环境变量和代码配置两种方式：

环境变量配置示例：

# 基本配置
OTEL_SERVICE_NAME=litellm-prod
OTEL_ENVIRONMENT_NAME=production
OTEL_MODEL_ID=gpt-4-prod

# 导出器配置
OTEL_EXPORTER=otlp_http
OTEL_ENDPOINT=https://api.honeycomb.io/v1/traces
OTEL_HEADERS=x-honeycomb-team=your-team-token

# 调试模式
DEBUG_OTEL=true

代码配置示例：

from litellm.integrations.opentelemetry import OpenTelemetry, OpenTelemetryConfig

# 自定义配置
otel_config = OpenTelemetryConfig(
    exporter="otlp_http",
    endpoint="https://api.honeycomb.io/v1/traces",
    headers="x-honeycomb-team=your-team-token"
)

# 初始化OpenTelemetry
otel_logger = OpenTelemetry(config=otel_config)

# 设置为全局回调
litellm.success_callback = [otel_logger]
litellm.failure_callback = [otel_logger]

追踪Span层次结构

LiteLLM的OpenTelemetry集成创建了多层次的Span结构，每个Span都包含丰富的元数据：

Span名称	类型	描述	关键属性
litellm_request	根Span	整个LLM请求的生命周期	model, provider, total_tokens, cost
raw_gen_ai_request	子Span	具体LLM提供商的调用	provider, model, api_base
postgres	子Span	数据库操作	query_type, table, duration
redis	子Span	缓存操作	operation, key, hit/miss
batch_write_to_db	子Span	批量写入操作	batch_size, write_duration

丰富的属性追踪

LiteLLM为每个Span添加了详细的属性信息，这些属性涵盖了LLM调用的各个方面：

请求级别属性：

{
    "model": "gpt-4",
    "provider": "openai",
    "max_tokens": 1000,
    "temperature": 0.7,
    "stream": False,
    "user": "user-12345"
}

响应级别属性：

{
    "response.model": "gpt-4",
    "response.usage.prompt_tokens": 150,
    "response.usage.completion_tokens": 200,
    "response.usage.total_tokens": 350,
    "response.cost": 0.021,
    "response.finish_reason": "stop"
}

性能指标：

{
    "duration_ms": 1250,
    "time_to_first_token_ms": 450,
    "tokens_per_second": 160,
    "throughput_tokens_sec": 155.2
}

动态头部支持

LiteLLM支持动态OpenTelemetry头部配置，允许基于每个请求配置不同的追踪目标：

# 动态头部配置示例
dynamic_headers = {
    "x-honeycomb-team": "team-a-token",
    "x-honeycomb-dataset": "team-a-dataset"
}

# 在请求中传递动态配置
response = completion(
    model="gpt-4",
    messages=messages,
    litellm_params={
        "dynamic_otel_headers": dynamic_headers
    }
)

服务级别追踪

除了LLM调用追踪，LiteLLM还提供了服务级别的追踪能力：

# 服务成功追踪
await otel_logger.async_service_success_hook(
    payload=service_payload,
    parent_otel_span=parent_span,
    start_time=start_time,
    end_time=end_time
)

# 服务失败追踪
await otel_logger.async_service_failure_hook(
    payload=service_payload,
    error="Service timeout",
    parent_otel_span=parent_span
)

调试与故障排除

LiteLLM提供了详细的调试功能来帮助诊断OpenTelemetry问题：

启用调试模式：

export DEBUG_OTEL=true

调试信息包括：

• Span创建和结束时间戳
• 属性设置详情
• 导出器连接状态
• 头部解析结果
• 错误和异常信息

最佳实践建议

1. 环境分离：为不同环境配置不同的OpenTelemetry端点
2. 采样策略：在生产环境中实施适当的采样率以避免数据过载
3. 敏感信息：确保不追踪敏感数据，使用属性过滤
4. 性能监控：监控OpenTelemetry导出器的性能影响
5. 错误处理：实现健壮的错误处理机制，避免追踪系统影响主业务

集成示例

完整的集成示例展示了如何在生产环境中配置和使用OpenTelemetry：

import os
from litellm import completion
from litellm.integrations.opentelemetry import OpenTelemetry

# 环境配置
os.environ["OTEL_SERVICE_NAME"] = "llm-gateway"
os.environ["OTEL_EXPORTER"] = "otlp_http"
os.environ["OTEL_ENDPOINT"] = "https://api.honeycomb.io/v1/traces"
os.environ["OTEL_HEADERS"] = "x-honeycomb-team=your-team-token"

# 初始化OpenTelemetry
otel_logger = OpenTelemetry()

# 配置回调
litellm.success_callback = [otel_logger]
litellm.failure_callback = [otel_logger]

# 执行LLM调用
response = completion(
    model="gpt-4",
    messages=[{"role": "user", "content": "Explain distributed tracing"}],
    max_tokens=500
)

通过LiteLLM的OpenTelemetry集成，团队可以获得深入的LLM应用可观测性，包括性能监控、故障诊断、成本分析和用户体验优化。这种集成为构建可靠、高效的LLM应用提供了坚实的基础设施支持。

总结

LiteLLM的可观测性体系通过内置日志系统、回调机制和第三方平台集成，为LLM应用提供了完整的监控、追踪和分析能力。系统支持多层次的日志架构、动态回调参数、丰富的监控指标收集以及分布式追踪功能。通过与MLflow、Langfuse、Prometheus和OpenTelemetry等工具的深度集成，LiteLLM确保了LLM应用在生产环境中的稳定性、性能可观测性和故障排查能力，为构建可靠的AI应用提供了坚实基础。

【免费下载链接】litellm Call all LLM APIs using the OpenAI format. Use Bedrock, Azure, OpenAI, Cohere, Anthropic, Ollama, Sagemaker, HuggingFace, Replicate (100+ LLMs) 项目地址: https://gitcode.com/GitHub_Trending/li/litellm