跳到主要内容

a6-plugin-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",
  "service_id": "",
  "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": "..." },
    "querystring": {}
  },
  "response": {
    "status": 200,
    "size": 123,
    "headers": { "content-type": "...", "content-length": "..." }
  },
  "server": {
    "hostname": "gateway-1",
    "version": "3.15.0"
  }
}

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

1. 用 http- logger 创建路由​

a6 route create -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": {
      "backend:8080": 1
    }
  }
}
EOF

2. 核查日志正在到达​

curl http://127.0.0.1:9080/api/hello
# Check your log collector for the entry

常见模式​

使用 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",
        "upstream_addr": "$upstream_addr"
      }
    }
  }
}

认证端点​

{
  "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"]
      ]
    }
  }
}

以换行符分隔的JSON （用于Elasticsearch批量API ）​

{
  "plugins": {
    "http-logger": {
      "uri": "http://elasticsearch:9200/_bulk",
      "concat_method": "new_line"
    }
  }
}

为高流量路由配置大批量发送​

{
  "plugins": {
    "http-logger": {
      "uri": "http://log-collector:8080/logs",
      "batch_max_size": 5000,
      "inactive_timeout": 30,
      "buffer_duration": 120,
      "max_retry_count": 3,
      "retry_delay": 2
    }
  }
}

配置同步示例​

version: "1"
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"
          uri: "$request_uri"
          status: "$status"
    upstream_id: my-upstream

故障排查​

现象原因解决方法
未收到日志uri 错误或端点不可用验证网关节点是否可以访问该端点
SSL 握手失败证书不受信任对自签名证书设置 ssl_verify: false
日志延迟inactive_timeout 过大降低 inactive_timeout 以加快发送
日志丢失缓冲区溢出增大 batch_max_size，并降低发送延迟
缺少请求正文include_req_body: false设置为 true，并留意内存开销
身份认证被拒绝auth_header 值错误提供完整的请求头值，例如 Bearer <token>

本文根据 api7/a6 仓库中的 a6-plugin-http-logger/SKILL.md 生成。可在 AI Agent Skills 页面浏览全部 Skill。