Antirion可观测性完整指南:请求日志、Prometheus指标、OTLP追踪与SLO告警

原创2026-11-06 21:06:361,857 阅读

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可观测性控制台总览:请求日志、Prometheus指标与SLO告警仪表盘

Antirion分析面板:LLM网关请求日志与Prometheus指标趋势图

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. 在控制台里查询与导出

Antirion请求日志界面:LLM网关调用记录、耗时与Prometheus指标对照

  • 控制台的 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 做了三重防护:

  1. 标签值默认截断到 128 字节(max_label_value_bytes 可调);
  2. 每个指标族最多 10000 条序列(max_series_per_family),超出的样本落入 _overflow 序列并计入 antirion_metrics_series_overflow_total;
  3. 直方图桶可按指标族覆盖(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. 告警规则与投递渠道

Antirion SLO告警控制台:LLM网关预算、延迟目标与告警规则配置

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/)支持可视化编辑、预览触发、手动测试投递,并保留每次交付的审计日志。

六、快速上手清单

  1. 启动:docker run -p 8080:8080 -p 8081:8081 eliasbiondo/antirion 即可(见 docs/getting-started.md);请求日志与 /metrics 默认开启,零配置可用;
  2. 接监控:Prometheus 抓取 admin 端口的 /metrics,优先盯 antirion_overhead_seconds、antirion_time_to_first_token_seconds、antirion_cost_usd_total 三个;
  3. 接追踪:配置 observability.traces.enabled: true + exporter.endpoint 指向 Collector,再设 viewer_url 打通"日志 → trace"跳转;
  4. 定 SLO:给核心路由声明 availability 99.9% + latency 目标;
  5. 接告警:一条 budget.threshold_crossed 事件规则 + Slack 渠道,成本失控当天就有通知;
  6. 调隐私:按合规需要收敛 client_ip: truncated、content_retention 与正文记录策略。

总结

Antirion 把 LLM 网关最常被抱怨的"黑盒"问题一次做透:请求日志细到每一次重试与毫秒级开销,Prometheus 指标内置且自带高基数保护,OTLP 追踪打通网关到上游的全链路,SLO 告警则基于真实的请求日志口径而不是拍脑袋的代理指标。四者共享同一份 observability 配置与同一套请求记录,意味着你在控制台、Prometheus 和追踪系统里看到的数据天然互相一致。如果你的团队正在把 LLM 调用接入生产,这套可观测性能力值得在第一天就打开。

登录后查看全文
antirion