API7 网关 AI Agent Skill：http-logger 插件

概览

http-logger 插件会以 JSON 形式将请求/响应日志推送到 HTTP 或 HTTPS 端点。日志会批量发送以提高效率，并支持使用 NGINX 变量自定义格式。你可以使用它将结构化日志发送到任意基于 HTTP 的日志后端（Elasticsearch、Loki、自定义 API 等）。

适用场景

• 将访问日志发送到基于 HTTP 的日志后端。
• 仅使用选定字段自定义日志格式。
• 有条件地捕获请求/响应体。
• 批量发送日志，并在失败时重试。

插件配置参考

字段	类型	是否必填	默认值	说明
uri	string	是	—	用于日志发送的 HTTP/HTTPS 端点
auth_header	string	否	—	Authorization 请求头值
timeout	integer	否	3	连接超时时间（秒）
log_format	object	否	—	自定义日志格式（支持 $variable 语法）
include_req_body	boolean	否	false	在日志中包含请求体
include_req_body_expr	array	否	—	请求体日志记录的条件表达式
include_resp_body	boolean	否	false	在日志中包含响应体
include_resp_body_expr	array	否	—	响应体日志记录的条件表达式
concat_method	string	否	"json"	批处理格式：json（数组）或 new_line（按换行符分隔）
ssl_verify	boolean	否	false	为 HTTPS 端点校验 SSL 证书

批处理参数

字段	类型	默认值	说明
batch_max_size	integer	1000	每批次的最大条目数
inactive_timeout	integer	5	刷新未完成批次前等待的秒数
buffer_duration	integer	60	强制刷新前最早条目的最大存留时间
max_retry_count	integer	0	失败时的重试次数
retry_delay	integer	1	重试之间的间隔秒数

默认日志条目格式

未设置自定义 log_format 时，每条日志包含：

{
  "client_ip": "127.0.0.1",
  "route_id": "1",
  "start_time": 1703907485819,
  "latency": 101.9,
  "apisix_latency": 100.9,
  "upstream_latency": 1,
  "upstream": "127.0.0.1:8080",
  "request": {
    "method": "GET",
    "uri": "/api/users",
    "url": "http://127.0.0.1:9080/api/users",
    "size": 194,
    "headers": { "host": "...", "user-agent": "..." }
  },
  "response": {
    "status": 200,
    "size": 123,
    "headers": { "content-type": "...", "content-length": "..." }
  }
}

分步操作：将日志发送到 HTTP 端点

1. 使用 http-logger 创建路由

为 default 网关组启用日志记录：

a7 route create --gateway-group default -f - <<'EOF'
{
  "id": "logged-api",
  "uri": "/api/*",
  "plugins": {
    "http-logger": {
      "uri": "http://log-collector:8080/logs",
      "batch_max_size": 100,
      "inactive_timeout": 10
    }
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": [{"host": "backend", "port": 8080, "weight": 1}]
  }
}
EOF

2. 为网关组启用全局日志

应用全局规则，记录 prod 网关组中的所有流量：

a7 global_rule create --gateway-group prod -f - <<'EOF'
{
  "id": "http-logger-global",
  "plugins": {
    "http-logger": {
      "uri": "http://log-collector:8080/global-logs",
      "batch_max_size": 500,
      "inactive_timeout": 30
    }
  }
}
EOF

常见模式

使用 NGINX 变量自定义日志格式

{
  "plugins": {
    "http-logger": {
      "uri": "http://log-collector:8080/logs",
      "log_format": {
        "@timestamp": "$time_iso8601",
        "client_ip": "$remote_addr",
        "host": "$host",
        "method": "$request_method",
        "uri": "$request_uri",
        "status": "$status",
        "latency": "$request_time"
      }
    }
  }
}

身份认证端点

{
  "plugins": {
    "http-logger": {
      "uri": "https://log-service.example.com/api/v1/logs",
      "auth_header": "Bearer eyJhbGciOiJIUzI1NiIs...",
      "ssl_verify": true,
      "timeout": 5
    }
  }
}

有条件地记录请求体

仅当存在查询参数时记录请求体：

{
  "plugins": {
    "http-logger": {
      "uri": "http://log-collector:8080/logs",
      "include_req_body": true,
      "include_req_body_expr": [
        ["arg_debug", "==", "true"]
      ]
    }
  }
}

故障排查

现象	原因	解决方法
未收到日志	uri 错误或端点不可用	验证网关节点是否可以访问该端点
SSL 握手失败	证书不受信任	对自签名证书设置 ssl_verify: false
日志延迟	inactive_timeout 过大	降低 inactive_timeout 以加快发送
日志丢失	缓冲区溢出	增大 batch_max_size，并降低发送延迟
身份认证被拒绝	auth_header 值错误	包含完整的请求头值（例如 Bearer <token>）
配置未生效	指定了错误的网关组	确保 --gateway-group 与目标网关组一致

配置同步示例

version: "1"
gateway_group: default
routes:
  - id: logged-api
    uri: /api/*
    plugins:
      http-logger:
        uri: http://log-collector:8080/logs
        batch_max_size: 200
        inactive_timeout: 10
        log_format:
          timestamp: "$time_iso8601"
          client_ip: "$remote_addr"
          method: "$request_method"
          status: "$status"
    upstream:
      type: roundrobin
      nodes:
        - host: backend
          port: 8080
          weight: 1

---

本页面由 api7/a7 仓库中的 a7-plugin-http-logger/SKILL.md 生成。你可以在 AI Agent Skills 页面查看所有技能。