跳到主要内容

请求日志输出

文档导航​

  • 本页：
    • log 插件配置
    • PostgreSQL 摘要
    • Kafka / HTTP 输出
    • raw 行为
    • 备注与边界行为
  • 子文档：

配置​

请求日志由静态配置 plugins.log.* 控制。

TODO：如果后续重新引入日志插件的动态全局配置，需要补齐 log_unknown_routes 与 log_unauthenticated_routes 的运行时接线。

当前 log 插件会同时做两件事：

  • 将请求日志摘要写入 PostgreSQL request_logs
  • 将统一的完整请求日志事件写出到日志目的地

可选地，还可以把完整日志 protojson 额外写入 request_logs.raw：

  • plugins.log.store_full_body_in_pg = true 时写入
  • 默认关闭
  • 关闭时 raw 为 NULL

其中：

  • destination = http：默认发送 Event 的 proto json 数组
  • destination = kafka：默认发送 Event 的 proto json 对象
  • destination = none：不发送事件，只写 PG

可通过 plugins.log.output_format = "json" | "binary" 显式选择日志目的地编码。未配置时默认 json。

PostgreSQL 摘要​

摘要落到 request_logs 表，裁剪发生在 PG 入库阶段，特点是：

  • 不存 request.body
  • 不存 response.body
  • 不存 upstreamRequests[].request.body
  • 不存 upstreamRequests[].response.body
  • 单独存 requested_model
  • 插件扩展字段统一落到 ext_fields
  • ext_fields 的当前已知 key / proto 索引见 日志扩展字段

摘要中会保留这些核心字段：

  • tenant_id
  • route_id
  • route_name
  • request_id
  • requested_model：真实模型请求中，客户端请求体里的原始 model
  • remote_addr
  • session_id：会话（session）插件提取到的会话 ID
  • request 摘要：url/path/method/header/protocol
  • response 摘要：code/header
  • upstreamRequests：按真实尝试顺序保存的上游请求/响应摘要数组；每项包含：
    • request：url/path/method/header/model
    • response：code/header
    • meta：attempt_index、upstream_id、upstream_name、upstream_api_key_id、provider_protocol、final、error
  • timing
  • duration
  • error
  • ext_fields

Kafka 事件​

当 destination = kafka 时，log 插件会在 PG 摘要写入成功后，再发送一条 logging.v1.Event。

Kafka 事件使用 oneof event 承载具体事件类型，当前只有一类：

  • request_log：统一的完整请求日志对象

其中 request_log 保留：

  • request.body
  • request.protocol
  • session_id
  • response.body
  • upstreamRequests[].request.model
  • upstreamRequests[].request.body
  • upstreamRequests[].response.body

如果开启 plugins.log.store_full_body_in_pg，相同的一份完整请求日志也会以 protojson 形式保存到 request_logs.raw，供 management API 的 GetFullRequestLog 优先读取；当 raw 不存在时，GetFullRequestLog 会回退到摘要结果。

Kafka message key 使用 request_id。

Kafka message value 的编码由 plugins.log.output_format 控制：

  • json：单个 Event 的 proto json 对象，默认行为
  • binary：protobuf binary

requested_model​

requested_model 与运行时模型解析使用同一套提取语义，只在这些真实模型请求路径上读取请求 JSON 的顶层 model：

  • POST /chat/completions
  • POST /responses
  • POST /messages
  • POST /embeddings

其他路径不会从请求体提取 requested_model。例如 GET /v1/models 即使带了 {"model":"..."} body，日志中的 requested_model 和 request 摘要里的 model 也保持为空。

HTTP 输出​

当 destination = http 时，当前默认输出 logging.v1.Event 的 proto json 数组。

也就是说，HTTP 与 Kafka 使用同一条事件结构，默认都使用 proto json：

其中：

  • HTTP 默认：proto json 数组
  • Kafka 默认：单个 Event 的 proto json 对象

HTTP 输出的顶层字段与 proto 保持一致：

  • request_log

其中插件扩展字段统一位于 request_log.ext_fields.*。当前已知 key / proto 索引见 日志扩展字段，具体字段解释见各插件文档。

如果配置 plugins.log.output_format = "binary"，HTTP 每次上报一个 logging.v1.Event 的 protobuf binary body，Content-Type 为 application/x-protobuf。

备注​

隐藏敏感信息​

Aidy Gateway 默认会隐藏日志中的敏感信息（如 API 密钥）。

可通过静态配置文件关闭：

[plugins.log]
hide_sensitive_data = false

未知路径​

当请求的 URL 匹配到路由，但不是已知的 AI path 时，只要日志插件已经启用，请求仍会按当前实现进入日志链路。

gateway 会在运行时解析前返回本地 HTTP 404，不会继续解析 upstream 候选，也不会向上游发起请求。

Chat 请求体解析​

当前 chat 请求在进入 forward_chat 链前，会先按入站路径解析为内部 IR：

  • /chat/completions
  • /responses
  • /messages

如果请求体无法通过对应入站协议的解析或校验，gateway 会直接返回本地 400 invalid chat request body: <reason>，而不会继续把该请求透传给上游做校验。

未知路由​

当请求的 URL 未能匹配任何路由的 prefix 时，会对请求响应 HTTP 441。

当开启静态配置 plugins.log.log_unknown_routes 时，对于未知路由仍会记录日志，此时 route_id = ":unknown"，tenant_id = ""。

Embeddings 响应体​

对于 /v1/embeddings 接口，当响应为成功（状态码在 200-299）时，日志会将 response.body 与 upstreamRequests[].response.body 标记为 <omitted>；当响应为错误（非 2xx）时，仍会记录响应体。