litellm 回调系统：5 个事件钩子 × 4 个监控平台的自定义日志与监控集成指南
【免费下载链接】litellmThe fastest, litest AI Gateway. Rust core with Python SDK. Call 100+ LLM APIs in OpenAI (or native) format with cost tracking, guardrails, load balancing, and logging [Bedrock, Azure, OpenAI, Anthropic, OpenAI, VertexAI, vLLM, Nvidia NIM]项目地址: https://gitcode.com/GitHub_Trending/li/litellm
多模型网关上线两周，混用了 6 个 provider 的 deployment，错误率突然涨了一倍，只能去各平台后台手动翻日志，对齐是哪个请求挂了、花了多少钱。litellm 回调系统把请求生命周期拆成几个固定事件点，所有 provider 的请求、响应、异常都能写进你自己指定的日志目标，排查时只需要看一处。
最小配置启用第一个回调
代理模式下三步即可，不需要写任何代码：
- 在配置文件里声明回调名，只写平台名，litellm 内部会注册对应的 logger：
# proxy_server_config.yaml general_settings: success_callback: ["langfuse"]- 导出该平台要求的凭据环境变量（Langfuse 对应
LANGFUSE_PUBLIC_KEY、LANGFUSE_SECRET_KEY），凭据清单可对照 集成目录文档。 - 重启进程，发一个测试请求，到 Langfuse 后台确认 trace 逐条出现即完成。
SDK 直连场景则是把回调实例传给completion()的callbacks参数，或挂到全局litellm.callbacks，效果相同。
5 个事件钩子的触发时机与可取数据
回调基类 CustomLogger 把一次调用切成下面的事件点，每个钩子都有async_*同名变体：
| 事件钩子 | 触发时机 | 可获取数据 | 典型用途 |
|---|---|---|---|
log_pre_api_call | 请求发往 provider 之前 | model、messages、完整 kwargs | 参数改写、请求拦截、前置审计 |
log_post_api_call | 响应解析完成之后 | 请求 + 响应 + start/end 时间戳 | 算耗时、统计 token 与成本 |
log_stream_event | 流式响应中每个 chunk | 当前 chunk 内容 | 流式转发、逐 chunk 打点 |
log_success_event | 调用成功收尾时 | 同 post 事件，无异常 | 成功侧指标、批量落盘 |
log_failure_event | 调用抛异常时 | 同 post 事件 + 异常信息 | 告警、错误类型分布 |
需要注意两点：同步与异步钩子是独立方法，只实现同步版在 async 路径上不会触发；流式调用只会走到log_stream_event，不会触发 post 钩子。
按场景选平台：告警、指标、追踪、质量对比表
内置适配器超过 15 个，按目的分四类选型更清晰：
| 场景 | 工具 | 核心能力 | 接入成本 |
|---|---|---|---|
| 告警响应 | SlackAlerting | 预算阈值（如用到 80%）、慢请求、hanging 请求经 webhook 推到 Slack/MS Teams，支持按告警类型分流不同渠道 | 低：一个 webhook URL + 阈值参数 |
| 性能观测 | Datadog | 调用延迟分位、按 token 的成本指标、错误类型分布，可走 API key 或本地 agent 两种通道 | 中：需 API key 或部署 agent |
| 调试追踪 | LangSmith | 以 span 串起完整调用链，看对话上下文与中间状态 | 低：2 个环境变量 |
| 质量监控 | Arize（Phoenix） | 评测、模型行为质量观测 | 高：需要额外配置评测流程 |
选型上，值班团队先上 SlackAlerting 兜底，性能调优再补 Datadog，开发和联调阶段用 LangSmith 最省事。
继承 CustomLogger 的最小自定义处理器模板
内置工具覆盖不了的场景（比如合规脱敏日志），继承基类重写对应钩子即可：
import json from litellm.integrations.custom_logger import CustomLogger class RedactedLogger(CustomLogger): def log_post_api_call(self, kwargs, response_obj, start_time, end_time): record = { "model": kwargs.get("model"), "duration_s": round(end_time - start_time, 3), # 不写 messages 原文，只留可追溯元数据 } with open("/var/log/litellm/access.log", "a") as f: f.write(json.dumps(record, ensure_ascii=False) + "\n")启用时completion(..., callbacks=[RedactedLogger(turn_off_message_logging=True)])。三个要点：turn_off_message_logging=True让标准日志 payload 不再携带消息原文，是控制日志体积的第一道闸；高 QPS 下不要逐条写，参考 CustomBatchLogger 做批量聚合上报；并发压力大的环境自行加采样（如 10% 记录全量、其余只记元数据）。
回调不触发、日志过大等常见坑排查
| 现象 | 原因 | 处理 |
|---|---|---|
| 回调完全不触发 | 只实现了同步钩子而请求走 async 路径，或事件类型没对上（流式只走log_stream_event） | 补实现async_log_*变体；流式场景单独实现 stream 钩子 |
| 日志体积暴涨 | 每条记录都带 messages 全文 | 构造时传turn_off_message_logging=True，或自行截断 payload 中的 content |
| 监控指标缺失 | Prometheus 指标服务未启动或指标未注册 | 检查 prometheus_services.py 中指标注册与抓取配置 |
| 只部分调用有数据 | general_settings漏写回调名，或凭据环境变量未设置，logger 初始化时静默跳过 | 对照 集成文档 补齐回调名与环境变量 |
| 代理端没数据、SDK 端有 | 代理读general_settings，SDK 读litellm.callbacks，两处配置不通用 | 明确生效面，两边各配一次 |
回调系统只覆盖日志与监控这一层：内容护栏、预算和限流由 guardrails 与 budget manager 各自负责，路由与负载均衡在 router 模块，混用时不要把它们的职责算到回调里。完整钩子签名（含 prompt 管理、pre-routing 等扩展钩子）以 CustomLogger 源码 为准，各平台的接入细节见 集成目录。
【免费下载链接】litellmThe fastest, litest AI Gateway. Rust core with Python SDK. Call 100+ LLM APIs in OpenAI (or native) format with cost tracking, guardrails, load balancing, and logging [Bedrock, Azure, OpenAI, Anthropic, OpenAI, VertexAI, vLLM, Nvidia NIM]项目地址: https://gitcode.com/GitHub_Trending/li/litellm
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
