Routic

可观测性与 Request ID

每个发往 Routic API 的请求都会被分配一个唯一的 request ID。理解它的用途，能帮你更快定位问题、更高效地与支持团队沟通。

什么是 Request ID？

Request ID 是一个唯一字符串，标识一次 API 请求在系统中的完整流转。它把你的客户端错误与服务端日志和计费记录关联起来。

格式：req_ + 32 位十六进制字符（如 req_a1b2c3d4e5f6789012345678abcdef01）。

如何获取 Request ID

从响应头获取

每个 API 响应都包含 X-Request-Id 头：

HTTP/1.1 200 OK
X-Request-Id: req_a1b2c3d4e5f6789012345678abcdef01
Content-Type: application/json

从错误载荷获取

错误响应在 JSON body 中包含 request_id：

{
  "error": {
    "message": "RPM 限制已超出，请 5 秒后重试。",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "request_id": "req_a1b2c3d4e5f6789012345678abcdef01"
  }
}

自行传入 Request ID

你可以在请求中传入 X-Request-Id 头，Routic 会使用你的值并在响应中原样回传。这适用于将你的内部链路追踪与 Routic 日志关联。

import openai

client = openai.OpenAI(
    base_url="https://api.routic.ai/v1",
    api_key="sk-xxxxxxxx",
    default_headers={"X-Request-Id": "my-trace-12345"},
)

如果不传，Routic 会自动生成一个。

Request ID 在系统中的流转

你的应用 → Routic API → 网关 → 模型提供商
   │           │          │          │
   └─ X-Request-Id ─┴── 日志 ──┴── 消费日志 ──┘
                                    │
                              usage_records
                          (gateway_request_id)
  1. 客户端发送请求（带或不带 X-Request-Id）
  2. Routic API 分配或保留该 ID，写入访问日志
  3. 网关处理请求，在消费日志中记录该 ID
  4. 用量同步将该 ID 作为 gateway_request_id 写入用量记录
  5. 计费通过此 ID 将用量记录关联到你的账户

这意味着同一个 request ID 可用于追踪：

  • API 访问日志（方法、路径、状态、耗时）
  • 网关消费日志（模型、token 数、成本）
  • 你的计费记录（用量、扣费）

用 Request ID 排障

什么时候用

场景做法
收到意外错误复制错误响应中的 request_id，发给支持团队。
用量缺失提供 request_id 和大约时间——支持可以查是否被记录。
账单与预期不符提供 request_id，支持可以对比网关成本与你的扣费。
延迟调查提供 request_id，支持可以查看服务端处理耗时。

最佳实践

  • 始终记录 request_id——不仅记录错误，成功请求也记录，方便回溯。
  • 同时记录时间戳——配合 request ID 缩小日志搜索范围。
  • 传入你自己的 X-Request-Id——如果你有内部链路追踪系统（如 OpenTelemetry），可以用 trace ID 作为 request ID。
import logging

logger = logging.getLogger("routic")

def call_api(messages):
    response = client.chat.completions.create(
        model="deepseek-r1",
        messages=messages,
    )
    rid = response._request_id  # 或从原始响应头获取
    logger.info(f"request_id={rid} model={response.model} tokens={response.usage.total_tokens}")
    return response

监控

健康检查

API 暴露了健康检查端点：

GET https://api.routic.ai/healthz

服务正常运行时返回 200 OK。此端点不检查数据库或缓存连通性——仅确认 API 进程存活。

可监控的指标

指标观察方式
API 可用性定期轮询 GET /healthz。
请求延迟在日志中检查 X-Request-Id + 时间戳。
Token 消耗检查每个响应的 usage 字段，或在控制台查看。
速率限制接近度关注 429 响应——说明接近限制。
错误率跟踪非 200 状态码的比例。

告警建议

  • 429 比率：如果 > 5% 的请求返回 429，考虑申请更高速率限制。
  • 5xx 比率：如果 > 1% 的请求返回 500/503，联系支持。
  • 延迟突增：如果 p99 延迟超过 30 秒，检查模型提供商状态。

相关文档