跳到主要内容

请求日志输出

文档导航​

  • 本页：
    • 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：发送 RequestLogEvent 的 proto json 数组
  • destination = kafka：发送 protobuf binary，消息结构见 aidy.v2.logging.v1.RequestLogEvent
  • destination = none：不发送事件，只写 PG

PostgreSQL 摘要​

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

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

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

  • tenant_id
  • route_id
  • route_name
  • request_id
  • requested_model：客户端请求体中的原始 model
  • remote_addr
  • 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 摘要写入成功后，再发送一条 aidy.v2.logging.v1.RequestLogEvent。

Kafka 事件只有一层：

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

其中 log 保留：

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

route_labels 仍然只出现在事件中，不会进入 PG 摘要。

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

Kafka message key 使用 request_id。

HTTP 输出​

当 destination = http 时，当前输出 aidy.v2.logging.v1.RequestLogEvent 的 proto json 数组。

也就是说，HTTP 与 Kafka 使用同一条事件结构，只是编码方式不同：

其中：

  • HTTP：proto json
  • Kafka：protobuf binary

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

  • log

其中插件扩展字段统一位于 log.ext_fields.*。当前已知字段与结构说明统一收口在 日志扩展字段。

备注​

隐藏敏感信息​

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

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

[plugins.log]
hide_sensitive_data = false

未知路径​

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

注意：当前只有当选中的 upstream 的 effective capability 包含 forward-unknown 时，未知路径才会继续向上游转发；否则会在运行时阶段被过滤掉。

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）时，仍会记录响应体。