LiteLLM Gateway Slack 告警集成预算告警框架、批量投递与高流量下的告警性能设计【免费下载链接】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本篇技术指南以 LiteLLM 仓库中 Slack Alerting 集成模块文档 为主体系统讲解 LiteLLM GatewayProxy的 Slack 告警子系统它如何把预算超限、模型宕机、请求挂起、日报/周报等事件批量聚合后投递到 Slack 或 MS Teams如何依靠缓存做告警去重与降噪以及budget_alert_types.py中预算告警策略框架的设计。读完本篇你能理解该模块的完整文件结构、核心配置参数与默认值、批量投递链路并知道如何扩展一种新的预算告警类型。模块定位与文件结构LiteLLM Gateway 在承载多团队、多 API Key、多部署deployment的 LLM 流量时需要一套统一的可观测告警通道。litellm/integrations/SlackAlerting/目录就是这套通道的实现它继承 LiteLLM 的回调日志体系CustomLogger在请求成功、失败、预算变化等事件发生时收集告警再通过 Webhook 批量推送到 Slack以及 MS Teams、Webhook、Email 等旁路通道。模块文档给出的目录职责如下结合仓库当前实际文件整理文件职责slack_alerting.py主文件。SlackAlerting类负责各类告警的判定、格式化、入队与投递batching_handler.py批处理 通过 Httpx 向 Slack 发送 POST 请求。告警每 10 秒或队列事件数超过 X 时发送以保证高流量下 LiteLLM 的性能budget_alert_types.py预算告警类型的策略框架抽象基类 各实体级别的告警实现 工厂函数utils.pySlack 告警专用工具函数如解析alert_to_webhook_url中的os.environ/...环境变量ms_teams.pyMS Teams 投递适配把告警文本包装为 Adaptive Card 负载hanging_request_check.py检测“挂起”的 LLM 请求超过阈值仍未返回user_spend_alerts.py按用户维度的日/月消费阈值与消费异常检测逻辑需要说明的一点文档中提到的types.pyAlertType 枚举所在文件在当前仓库结构中已迁移到公共类型目录 litellm/types/integrations/slack_alerting.py其中定义了AlertType枚举、SlackAlertingArgs参数模型、DEFAULT_ALERT_TYPES等后文会逐一展开。主类 SlackAlerting构造参数与配置项SlackAlerting定义在 slack_alerting.py继承自CustomBatchLogger位于 litellm/integrations/custom_batch_logger.py。构造函数签名与默认值如下def __init__( self, internal_usage_cache: DualCache | None None, # 内部用量缓存内存 Redis用于告警去重 alerting_threshold: float | None None, # 慢请求/挂起请求阈值秒None 时默认 300 alerting: list | None [], # 启用的通道[slack]、[slack, email] 等 alert_types: list[AlertType] DEFAULT_ALERT_TYPES, alert_to_webhook_url: dict[AlertType, list[str] | str] | None None, # 按告警类型分流到不同频道 alerting_args{}, # 对应 SlackAlertingArgs 的可选覆盖项 default_webhook_url: str | None None, alert_type_config: dict[str, dict] | None None, # 按类型启用 digest 聚合模式 **kwargs, ):几个关键行为慢请求阈值alerting_threshold缺省为 300 秒见 slack_alerting.py即一次 LLM 调用耗时超过 5 分钟才触发llm_too_slow告警。Webhook URL 解析alert_to_webhook_url会先经过 utils.py 的process_slack_alerting_variables处理——值中以os.environ/开头的条目会被替换为对应环境变量的实际取值从而支持“不同告警类型路由到不同 Slack 频道且频道 URL 不写死在配置里”。HTTP 客户端实例自带一个专用的异步 Httpx 客户端get_async_httpx_client(llm_providerhttpxSpecialProvider.LoggingCallback)所有告警请求都不占用 LLM 调用所使用的连接池。SlackAlertingArgs可调参数与默认值alerting_args会被构造为 Pydantic 模型SlackAlertingArgstypes/integrations/slack_alerting.py。它的全部字段与默认值如下表参数默认值说明daily_report_frequency4320012 小时部署延迟/失败日报的发送频率秒支持环境变量SLACK_DAILY_REPORT_FREQUENCY覆盖report_check_interval3005 分钟后台进程检查“是否该发日报”的轮询间隔秒budget_alert_ttl8640024 小时预算告警的缓存 TTL同一预算事件在 TTL 内不重复告警outage_alert_ttl60模型级宕机告警的错误统计时间窗口秒region_outage_alert_ttl60提供商区域级宕机告警的错误统计时间窗口秒minor_outage_alert_threshold5窗口内错误数达到 5 触发“次要宕机”告警400 不计入major_outage_alert_threshold10错误数达到 10 触发“主要宕机”告警max_outage_alert_list_size10缓存中最多保存的错误码数量防止内存泄漏log_to_consoleFalse为 True 时把告警 payload 打印到控制台调试用daily_spend_per_user_thresholdNone单用户当日UTC消费超过该美元金额即告警默认关闭monthly_spend_per_user_thresholdNone单用户当月消费阈值默认关闭spend_anomaly_multiplier3.0今日消费超过“过去 N 天日均”的该倍数时判定为异常spend_anomaly_baseline_days7异常检测使用的基线天数spend_anomaly_min_spend10.0触发异常告警所需的当日最低消费降低误报user_spend_check_interval3600用户消费阈值/异常检查的周期秒最小 60Gateway 配置示例结合 ProxyConfig 的update_values接受的字段alerting、alerting_threshold、alert_types、alerting_args、alert_to_webhook_url、alert_type_config一个典型的 Gateway YAML 配置如下该示例为配置文件写法非仓库内文件model_list: - model_name: gpt-4o litellm_params: model: gpt-4o api_key: os.environ/OPENAI_API_KEY general_settings: # 启用的告警通道webhook/email 为预算告警的旁路通道 alerting: - slack - email # 慢请求阈值秒 alerting_threshold: 300 # 按告警类型把消息路由到不同频道URL 用环境变量注入 alert_to_webhook_url: budget_alerts: os.environ/SLACK_BUDGET_WEBHOOK_URL outage_alerts: os.environ/SLACK_OUTAGE_WEBHOOK_URL alerting_args: budget_alert_ttl: 86400 # 预算告警 24 小时内不重复 minor_outage_alert_threshold: 5 major_outage_alert_threshold: 10 log_to_console: true # 排障时建议打开运行时SlackAlerting按“alert_to_webhook_url[alert_type]→default_webhook_url→ 环境变量SLACK_WEBHOOK_URL或ALERTING_WEBHOOK_URL”的优先级解析投递地址slack_alerting.py三者都缺失时会抛出ValueError。若alerting中包含ms_teams则额外要求设置MS_TEAMS_WEBHOOK_URL环境变量否则该条告警会被丢弃并记录错误日志见 slack_alerting.py 与 ms_teams.py。批量投递机制10 秒窗口 队列合并batching_handler.py是整个模块的投递核心。模块文档明确指出“Slack alerts are sent every 10s or when events are greater than X events. Done to ensure litellm has good performance under high traffic”见 batching_handler.py 的模块注释。其工作链路是入队SlackAlerting.send_alert(...)slack_alerting.py并不直接发 HTTP 请求而是把{url, headers, payload, alert_type}追加进log_queue。send_alert内部还承担了通道分发webhook通道把预算事件以结构化 JSONWebhookEventPOST 到WEBHOOK_URLemail通道把预算事件通过 SMTP 发信slack/ms_teams通道才进入消息队列。定时冲刷继承自CustomBatchLogger的periodic_flush每 10 秒litellm.DEFAULT_FLUSH_INTERVAL_SECONDS把队列内容一次性发出SlackAlerting覆写了periodic_flush在冲刷队列前先冲刷 digest 聚合桶见下文slack_alerting.py。满额即时冲刷队列长度达到batch_sizelitellm.DEFAULT_BATCH_SIZE时立即触发flush_queue避免高流量下告警积压。合并去重squashasync_send_batch先调用 squash_payloads把同一轮窗口内相同 (url, alert_type)的告警合并为一个条目并累加count再用asyncio.gather并发发送。发送时若count 1会在消息头部加上[Num Alerts: {count}]前缀batching_handler.py——一次宕机引发的 50 条重复告警在 Slack 里只会看到 1 条带计数的前缀消息。容错单条发送失败非 200 或异常只写 debug 日志不中断整批当alerting_args.log_to_console为 True 时 payload 会同时打到verbose_proxy_logger方便没有 Slack 权限时本地排障。MS Teams 走同一个队列队列项带formatms_teams标记发送前由 build_ms_teams_payload 把纯文本包装成AdaptiveCard v1.4的 message attachmentTeams Incoming Webhook 要求负载形态不同Slack 则是{text: ...}的裸 payload。Digest 聚合模式send_alert还内建了比 squash 更强的聚合若某告警类型在alert_type_config中启用了digest模型AlertTypeConfigtypes/integrations/slack_alerting.py该类型的告警不会逐条发送而是按(alert_type, model, api_base)三元组分桶累计count直到digest_interval默认 86400 秒即 24 小时到期由_flush_digest_buckets生成一条“Digest”汇总消息再走正常批量通道slack_alerting.py。这是面向高频低价值告警如单条 LLM 异常的降噪手段。告警类型体系AlertType 与 DEFAULT_ALERT_TYPESAlertType是字符串枚举types/integrations/slack_alerting.py覆盖 LLM 运行、预算与消费、数据库、报表、部署、宕机、回退与资源管理等事件族LLM 相关llm_exceptions调用失败、llm_too_slow响应过慢、llm_requests_hanging请求挂起预算与消费budget_alerts、spend_reports、failed_tracking_spend、user_spend_thresholds、user_spend_anomalies数据库db_exceptions报表daily_reports部署cooldown_deployment、new_model_added、model_deprecation_warnings宕机outage_alerts模型级、region_outage_alerts提供商区域级回退fallback_reports资源管理事件虚拟 Key 的创建/更新/删除、团队与内部用户的创建/更新/删除。未显式指定alert_types时使用DEFAULT_ALERT_TYPES白名单types/integrations/slack_alerting.py它开启了慢/挂起/异常、预算与消费报表、数据库异常、日报、部署、宕机、回退等绝大多数类型唯独不含虚拟 Key/团队/用户管理事件——这类审计告警需显式加入alert_types才会投递。每条告警统一由send_alert组装消息头Alert type / Level / Timestamp / Message并附请求模型、API Base如有与PROXY_BASE_URL便于从 Slack 消息直接定位实例与部署slack_alerting.py。预算告警框架budget_alert_types.py详解这是模块文档着墨最多的部分budget_alert_types.py提供了一套面向不同预算实体代理、用户、团队、Key 等的策略框架用于回答“这条预算告警属于哪个实体、消息前缀是什么、用哪个 ID 做去重”。抽象基类与工厂函数文档定义的框架接口为get_event_group()返回该告警对应的Litellm_EntityTypeget_event_message()返回告警消息前缀get_id(user_info)返回用于缓存/追踪的实体 ID。对照当前源码budget_alert_types.py抽象基类BaseBudgetAlertType保留了其中两个抽象方法get_event_message()与get_id(user_info)从源码结构看事件分组信息改由调用方传入的CallInfo.event_group携带budget_alerts()直接使用user_info.event_group判断是否发送slack_alerting.py因此文档示例中的get_event_group()调用在当前版本中应理解为该演进前的接口。工厂函数get_budget_alert_type(type)按告警类型字符串返回对应策略实例from litellm.integrations.SlackAlerting.budget_alert_types import get_budget_alert_type budget_alert_class get_budget_alert_type(user_budget) event_message budget_alert_class.get_event_message() # User Budget: cache_id budget_alert_class.get_id(user_info) # user_id当前工厂支持的全部字符串键及其映射budget_alert_types.py类型字符串策略类消息前缀去重 ID 来源proxy_budgetProxyBudgetAlertProxy Budget:固定default_id全局一条soft_budgetSoftBudgetAlertSoft Budget Crossed:团队场景取team_id否则取tokenuser_budgetUserBudgetAlertUser Budget:user_idteam_budgetTeamBudgetAlertTeam Budget:team_idorganization_budgetOrganizationBudgetAlertOrganization Budget:organization_idtoken_budget/max_budget_alertTokenBudgetAlertKey Budget:tokenprojected_limit_exceededProjectedLimitExceededAlertKey Budget: Projected Limit Exceededtokenproject_budgetProjectBudgetAlertProject Budget:token注意两点实现细节其一token_budget与max_budget_alert复用同一个TokenBudgetAlert实例Key 预算的两种触发口径其二传入未知字符串时工厂兜底返回ProxyBudgetAlert()而不是抛错——从源码结构看这是让未知预算事件也能以代理级告警形式被看见的防御性设计。触发条件与防骚扰去重预算事件的判定在_get_event_and_event_message中完成slack_alerting.py核心规则软预算spend soft_budget时产生soft_budget_crossed事件消息追加Total Soft Budget: {soft_budget}硬预算三档spend max_budget产生budget_crossed预算已击穿剩余预算占比 ≤ 5% 产生threshold_crossed“5% Threshold Crossed”≤ 15% 产生threshold_crossed“15% Threshold Crossed”。占比由_get_percent_of_max_budget_left计算5%/15% 常量定义在 types/integrations/slack_alerting.py预防性告警projected_limit_exceeded事件在“按当前速率推算将超预算”时提前触发。发送前还有一层缓存去重slack_alerting.py以budget_alerts:{event}:{实体ID}为缓存键查询internal_usage_cacheDualCache内存 Redis命中则跳过未命中则发送并写入SENT标记TTL 即alerting_args.budget_alert_ttl默认 24 小时。这保证“同一 Key 同一天击穿同一档预算只会收到一条 Slack 消息”多实例部署下依靠 Redis 共享去重状态。预算告警同时是多通道事件send_alert中若alerting含webhook会先把结构化WebhookEvent含 spend、max_budget、token、team_id、user_email、projected_spend 等字段POST 到WEBHOOK_URL若含email则通过 SMTP 发送预算邮件团队预算击穿还会触发send_team_budget_alert补充团队邮件slack_alerting.py。扩展新预算告警类型文档给出的扩展方式在源码中依然成立新建一个继承BaseBudgetAlertType的类实现get_event_message()与get_id()再把它注册进get_budget_alert_type()的alert_types字典并同步扩展该函数的Literal类型参数即可。策略对象是单例式的工厂内直接实例化因此无需依赖注入。其他核心告警链路除了预算告警模块文档提到的“不同种类的告警”还覆盖以下链路均复用同一套批量投递与去重基础设施慢请求与挂起请求llm_too_slow注册为 success 回调ProxyConfig.update_values 会把response_taking_too_long_callback加入litellm成功回调。响应耗时超过alerting_threshold即发送消息包含模型、API Base、前 100 字符的 messages受litellm.redact_messages_in_exceptions保护以及各部署延迟slack_alerting.py。llm_requests_hanging请求进入时写入AlertingHangingRequestCheck的内存缓存TTL alerting_threshold * 1.5 60s保证跨过阈值后仍有检查窗口hanging_request_check.py后台任务每alerting_threshold / 2秒扫描最旧的 20 条记录MAX_OLDEST_HANGING_REQUESTS_TO_CHECK对既无request_status:success/fail标记又超龄的请求发送一条 Medium 级告警并用alerted标志保证每次挂起只告警一次。宕机告警模型级 / 区域级模型级outage_alerts失败回调中仅统计 408 与 ≥500 的错误码以model_id为缓存键在outage_alert_ttl默认 60s窗口内累积错误数达到minor_outage_alert_threshold发“Minor Service Outage”Medium 级达到major_outage_alert_threshold发“Major Service Outage”High 级消息含提供商、API Base、错误码分布与最后检查时间slack_alerting.py。区域级region_outage_alerts缓存键为provider region且额外要求至少2 个不同 deployment在同一区域报错才判定区域宕机避免单个坏部署刷爆告警slack_alerting.py。日报、消费报表与用户消费监控daily_reports每次成功/失败事件把“失败次数”“每 output token 延迟”累加进缓存键形如{deployment_id}:failed_requests_daily_metrics调度器每report_check_interval默认 5 分钟带 ±3s 抖动检查一次距上次发送达到daily_report_frequency默认 12 小时后推送“Top 5 失败最多部署 Top 5 最慢部署”日报并在多实例间用 Pod 锁SLACK_DAILY_REPORT_LOCK_ID防止重复发送发完清空指标防止内存泄漏slack_alerting.py。spend_reportssend_weekly_spend_report默认 7 天格式如7d与send_monthly_spend_report按团队/标签汇总消费用weekly_spend_report_sent_{起}_{止}之类的缓存键保证每期只发一次slack_alerting.py。用户消费user_spend_thresholds/user_spend_anomalies由send_user_spend_alerts每user_spend_check_interval驱动阈值与异常判定逻辑在 user_spend_alerts.py每个用户每个周期同样通过缓存键去重。模型生命周期与审计事件new_model_added在网关新增模型时推送模型信息与可直接复制的 OpenAI SDK 调用示例slack_alerting.pymodel_deprecation_warnings由独立后台循环驱动先查“近一天是否已发过”缓存键model_deprecation_alert_sent再尝试获取 Pod 锁SLACK_MODEL_DEPRECATION_LOCK_ID确保多副本集群每天只发一条slack_alerting.py虚拟 Key、团队、内部用户的增删改事件通过send_virtual_key_event_slack统一输出操作者与参数摘要slack_alerting.py。启动装配ProxyConfig 如何接入告警Gateway 侧的装配逻辑值得了解因为它决定了告警何时“真正通电”。ProxyConfig在初始化时创建SlackAlerting实例此时alertingNone不启用任何通道utils.py当配置加载完成后调用update_values若alerting含slack/ms_teams才把SlackAlerting注册进litellm.logging_callback_manageradd_litellm_callback处理失败事件add_litellm_success_callback挂慢请求检查——源码注释明确强调“告警关闭时绝不注册回调”utils.py。startup_event则负责按已启用的alert_types拉起后台任务daily_reports启日报循环、llm_requests_hanging启挂起请求循环、model_deprecation_warnings启弃用检查循环utils.py。这也解释了为什么这些报表类告警在update_values中被再次注册回调配置可在启动后热加载注册时机必须兼容两种路径。小结LiteLLM Gateway 的 Slack 告警集成把“事件采集 → 去重降噪 → 批量投递 → 多通道分发”做成了完整管道SlackAlerting.send_alert统一收口消息格式化与通道分发batching_handler以 10 秒窗口 满额冲刷 (url, alert_type) 合并保证高流量下不发洪水budget_alert_types用策略模式把不同预算实体的告警差异收敛到工厂函数SlackAlertingArgs则把所有可调阈值TTL、窗口、倍数、间隔显式化并支持环境变量覆盖。对运维者而言关键调优点是alerting_threshold慢请求灵敏度、alert_to_webhook_url频道分流、alerting_args去重窗口与宕机阈值以及alert_type_config的 digest 模式对扩展者而言新增一类预算告警只需实现两个方法并注册进工厂字典。核心文件索引模块说明Readme.md主实现slack_alerting.py、batching_handler.py、budget_alert_types.py类型与参数模型types/integrations/slack_alerting.py批量基类custom_batch_logger.pyGateway 装配proxy/utils.py【免费下载链接】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），仅供参考
