Antirion可观测性完整指南:请求日志、Prometheus指标、OTLP追踪与SLO告警
Antirion可观测性完整指南:请求日志、Prometheus指标、OTLP追踪与SLO告警
Antirion 是最快的开源 AI Gateway(LLM 网关):一个二进制内置管理控制台,把 OpenAI、Anthropic、Gemini、Bedrock 等各家模型调用统一路由、限流、计费和观察。它的可观测性由四根支柱组成——请求日志(Request Log)、Prometheus 指标、OTLP 追踪、SLO 告警,全部由 observability 配置段驱动,源码集中在 crates/antirion-obs/ 与 crates/antirion-runtime/src/alerting/。本文将带你逐一拆解这四块能力,以及如何把它们用起来。
一、Antirion 可观测性架构全景
Antirion 对"可观测"的理解很务实:
- 每个请求通过鉴权后,各阶段(缓存查询、路由决策、每次 upstream 尝试、流式转发)都会把自己的事实写入请求日志草稿(crates/antirion-obs/src/record.rs);
- 结算(settle)时一次性产出三样东西:JSON 日志记录、Prometheus 指标样本、OTel span,然后才交给存储与外部 sink;
- 被拒绝的请求(鉴权前失败)不写日志但照样计入指标,所以监控不会"漏掉"攻击流量;
- 集群模式下每个节点直读共享存储(PostgreSQL),日志不跨节点拷贝。
这些机制的完整说明见 docs/development.md。
二、请求日志:让每次 LLM 调用都有据可查
1. 一条请求日志里有什么
请求日志记录固定为 schema v1,约 70 个字段,覆盖排障所需的几乎所有事实(crates/antirion-obs/src/record.rs):
| 类别 | 字段示例 | 用途 |
|---|---|---|
| 身份与链路 | request_id、trace_id、span_id、node_id |
与 OTel 追踪互相关联 |
| 路由决策 | requested_model、model、route、provider、deployment |
看请求实际去了哪 |
| 重试明细 | attempt_count、attempts[](含每次 duration_ms、ttft_ms、failure_class) |
定位是哪次尝试失败 |
| 性能 | timing:total_ms、overhead_ms、upstream_ms、ttft_ms、tpot_ms |
区分网关自身开销与上游耗时 |
| 用量与成本 | usage(input/output/缓存/多模态 token)、cost(USD,含 status: exact/estimated) |
账单核对 |
| 安全 | guardrails[]、degraded[]、client_disconnected |
审计与安全复盘 |
网关自身开销(overhead)有独立的计算公式,timing.overhead_ms 就是"Antirion 为这次请求多花了多少时间"——这是评估网关性能的关键指标。
2. 在控制台里查询与导出
- 控制台的 Request Log 页面(前端源码 console/src/features/request-log/)支持按组织、密钥、模型、状态码、标签等维度过滤、排序和导出;
- 每条记录可下钻到完整 JSON、请求/响应头、被截断的正文内容;
- 记录结构本身也有 JSON Schema,可通过 Admin API
GET /admin/v1/logs/schema获取,方便写入下游分析管道; - Analytics 页面(console/src/features/analytics/)基于预聚合的 rollup(每分钟/时/日,附 DDSketch 分位数草图,见 crates/antirion-obs/src/sketch.rs)回答"过去 30 天 P99 延迟和花费趋势"这类问题,无需全表扫描。
3. 保留策略与隐私
observability.request_logs 下的关键开关(完整定义见 schema/antirion-config.schema.json):
retention/content_retention:记录与正文可分别设置保留期,正文先到期先删;client_ip: full | truncated | none:截断模式只保留 IPv4 /24、IPv6 /48,降低 PII 风险;content.max_body_bytes(默认 1MiB):正文截断上限;sinks.http[]:批量推送到你的 ELK/Loki/Langfuse,也支持 OTLP logs 导出(每条记录一个 LogRecord,直接携带 trace/span id);- 密钥级还有
policies.observability.content.redact_pii等策略,可对特定密钥单独关闭内容记录。
三、Prometheus 指标:开箱即用的 LLM 网关监控
1. 核心指标清单
指标注册表内置于网关(crates/antirion-obs/src/metrics/catalog.rs),无需任何 SDK,直接抓取:
| 指标 | 类型 | 含义 |
|---|---|---|
antirion_request_duration_seconds |
Histogram | 请求总耗时 |
antirion_overhead_seconds |
Histogram | 网关自身增加的延迟 |
antirion_time_to_first_token_seconds |
Histogram | TTFT(首 token 延迟) |
antirion_time_per_output_token_seconds |
Histogram | TPOT(每输出 token 耗时) |
antirion_tokens_total / antirion_token_usage |
Counter/Histogram | 按字段拆分的 token 用量 |
antirion_cost_usd_total |
Counter | 按 model/provider 计费的美元成本 |
antirion_retries_total / antirion_fallbacks_total |
Counter | 同部署重试 / 跨部署降级次数 |
antirion_cache_lookups_total / antirion_cache_writes_total |
Counter | 响应缓存命中情况 |
antirion_guardrail_checks_total |
Counter | Guardrail 检查次数与耗时 |
antirion_rate_limited_total / antirion_auth_failures_total |
Counter | 限流拒绝与鉴权失败 |
antirion_dependency_up |
Gauge | 存储等依赖是否降级 |
默认在 admin 监听器的 observability.metrics.path(默认 /metrics)暴露,支持 Prometheus 0.0.4 与 OpenMetrics 文本格式;auth: required 为默认值,避免指标端点裸奔。
2. 高基数的自我保护
LLM 场景的标签(model、deployment、key)容易撑爆时序库,Antirion 做了三重防护:
- 标签值默认截断到 128 字节(
max_label_value_bytes可调); - 每个指标族最多 10000 条序列(
max_series_per_family),超出的样本落入_overflow序列并计入antirion_metrics_series_overflow_total; - 直方图桶可按指标族覆盖(
buckets),还能用exclude整族下线不需要的指标。
3. 不想被 Prometheus 抓取?OTLP 主动推送
observability.metrics.otlp 打开后,注册表的累计状态按 interval 主动推送到你的 OTel Collector,端点、压缩、TLS 均可配置——适合云厂商托管的监控服务。
四、OTLP 追踪导出:从网关到上游的全链路
Antirion 的 span 遵循 OpenTelemetry GenAI 语义约定(固定 core-1.41.1,可选实验线),每个 upstream 尝试都携带自己的 span 作为父级下发,因此网关 → 上游这一段链路是连续可追的(crates/antirion-obs/src/trace/)。
observability.traces 配置要点(schema/antirion-config.schema.json):
- 三种导出协议:
grpc(默认)、http/protobuf、http/json,对应exporter.endpoint指向 OTel Collector; - 采样器:
always_on/always_off/ratio/parent_based_ratio(默认,ratio=1.0),高流量可降到 0.1 控制成本; propagate_to_upstream: true(默认):把 trace 上下文注入上游请求,支持端到端追踪;header_attributes:把自定义请求头提升为 span 属性(凭据类头被拒绝);viewer_url:外部追踪查看器链接模板(含{trace_id}占位符),控制台请求详情里会直接渲染成跳转链接,点日志即开 trace;- 丢弃的 span 计数在
antirion_trace_spans_dropped_total,队列积压可观测。
导出失败的 sink 会让响应头 x-antirion-degraded 带上 observability 标记——网关的遥测问题本身也是可观测的。
五、SLO 与告警:预算烧穿、部署挂掉,主动通知你
1. 定义 SLO 目标
在 observability.slos 中声明式定义服务级目标,窗口 1–90 天(默认 30 天):
observability:
slos:
core-availability:
kind: availability # 默认;另一种是 latency
objective: 0.99
fast-ttft:
kind: latency
objective: 0.95
latency_threshold_ms: 1500
scope:
model: gpt-4o # 可限定 provider/model/route/组织/团队/项目/密钥
计算口径非常克制(crates/antirion-runtime/src/alerting/slo.rs):只有 5xx 且由网关或上游造成的失败才计为不可用;调用方自身错误、限额/预算拒绝、Guardrail 拦截都是 4xx,计入请求数但不计为失败——SLO 不会冤枉业务方。SLO 状态与可用性报表可通过 Admin API GET /runtime/slos、/reports/availability 查询。
2. 告警规则与投递渠道
observability.alerts 三层结构:
- rules(规则):两种触发器——
metric:指标 + 比较符 + 阈值(如budget_projection_ratio预算消耗比超阈);event:订阅事件,如budget.exhausted、budget.threshold_crossed、deployment.state_changed、auth.login_failed、alert.fired等;
- channels(渠道):Slack webhook、PagerDuty(Events API v2)、邮件(需开启 SMTP)、通用 webhook;
- webhooks(事件流):按
*/prefix.*模式订阅事件,推送到你的自建系统。
规则引用的渠道、升级渠道都必须真实存在,配置校验会直接拒绝悬空引用(crates/antirion-config/src/alert_rules.rs)。控制台的 Alerts 页面(console/src/features/alerts/)支持可视化编辑、预览触发、手动测试投递,并保留每次交付的审计日志。
六、快速上手清单
- 启动:
docker run -p 8080:8080 -p 8081:8081 eliasbiondo/antirion即可(见 docs/getting-started.md);请求日志与/metrics默认开启,零配置可用; - 接监控:Prometheus 抓取 admin 端口的
/metrics,优先盯antirion_overhead_seconds、antirion_time_to_first_token_seconds、antirion_cost_usd_total三个; - 接追踪:配置
observability.traces.enabled: true+exporter.endpoint指向 Collector,再设viewer_url打通"日志 → trace"跳转; - 定 SLO:给核心路由声明 availability 99.9% + latency 目标;
- 接告警:一条
budget.threshold_crossed事件规则 + Slack 渠道,成本失控当天就有通知; - 调隐私:按合规需要收敛
client_ip: truncated、content_retention与正文记录策略。
总结
Antirion 把 LLM 网关最常被抱怨的"黑盒"问题一次做透:请求日志细到每一次重试与毫秒级开销,Prometheus 指标内置且自带高基数保护,OTLP 追踪打通网关到上游的全链路,SLO 告警则基于真实的请求日志口径而不是拍脑袋的代理指标。四者共享同一份 observability 配置与同一套请求记录,意味着你在控制台、Prometheus 和追踪系统里看到的数据天然互相一致。如果你的团队正在把 LLM 调用接入生产,这套可观测性能力值得在第一天就打开。



