跳到主要内容
版本：3.10.x

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

概览​

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

适用场景​

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

插件配置参考​

字段类型是否必填默认值说明
uristring是—用于日志发送的 HTTP/HTTPS 端点
auth_headerstring否—Authorization 请求头值
timeoutinteger否3连接超时时间（秒）
log_formatobject否—自定义日志格式（支持 $variable 语法）
include_req_bodyboolean否false在日志中包含请求体
include_req_body_exprarray否—请求体日志记录的条件表达式
include_resp_bodyboolean否false在日志中包含响应体
include_resp_body_exprarray否—响应体日志记录的条件表达式
concat_methodstring否"json"批处理格式：json（数组）或 new_line（按换行符分隔）
ssl_verifyboolean否false为 HTTPS 端点校验 SSL 证书

批处理参数​

字段类型默认值说明
batch_max_sizeinteger1000每批次的最大条目数
inactive_timeoutinteger5刷新未完成批次前等待的秒数
buffer_durationinteger60强制刷新前最早条目的最大存留时间
max_retry_countinteger0失败时的重试次数
retry_delayinteger1重试之间的间隔秒数

默认日志条目格式​

未设置自定义 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 创建路由​

启用 logging 用于 网关组 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 页面查看所有技能。