跳到主要内容

clickhouse-logger

clickhouse-logger 插件将请求和响应日志分批发送到 ClickHouse。插件既可以写入默认的网关日志条目，也可以写入在插件实例或插件元数据中配置的自定义格式。

示例​

以下示例会配置当前版本的 ClickHouse 服务器，并验证默认和自定义网关日志格式。

本地评估凭据

为确保工作流可复现，示例使用 HTTP 连接和固定的本地密码。生产环境中，请使用 TLS，将 ClickHouse 密码存储在密钥管理器中，并保持启用 ssl_verify。

使用专用数据库和用户启动 ClickHouse。Docker 设置使用专用网络，以便正在运行的 APISIX 或 API7 网关容器可以通过容器名称访问 ClickHouse。

将 GATEWAY_CONTAINER 设置为正在运行的 APISIX 或 API7 网关容器名称。创建专用网络并将网关连接到该网络：

export GATEWAY_CONTAINER=replace-with-gateway-container-name

docker network create gateway-clickhouse-net
docker network connect gateway-clickhouse-net "$GATEWAY_CONTAINER"

在同一网络中启动 ClickHouse，并将其 HTTP API 绑定到主机回环接口：

docker run -d \
  --name clickhouse-server \
  --network gateway-clickhouse-net \
  -p 127.0.0.1:8123:8123 \
  -e CLICKHOUSE_DB=apisix_logs \
  -e CLICKHOUSE_USER=apisix_logger \
  -e CLICKHOUSE_PASSWORD=apisix-logger-pass \
  -e CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT=1 \
  --ulimit nofile=262144:262144 \
  clickhouse/clickhouse-server:26.8.5.13

等待 HTTP API 就绪：

until curl -fsS -u "apisix_logger:apisix-logger-pass" \
  "http://127.0.0.1:8123/ping" | grep -q "Ok"; do
  sleep 2
done

以默认格式记录请求日志​

以下示例将插件默认的请求和响应日志条目写入 ClickHouse。

在 ClickHouse 数据库中创建一个名为 default_logs 的表，其列对应于你的日志格式：

curl "http://127.0.0.1:8123" -X POST -d '
  CREATE TABLE apisix_logs.default_logs (
    host String,
    client_ip String,
    route_id String,
    service_id String,
    start_time String,
    latency String,
    upstream_latency String,
    apisix_latency String,
    consumer String,
    request String,
    response String,
    server String,
    PRIMARY KEY(`start_time`)
  )
  ENGINE = MergeTree()
' -u "apisix_logger:apisix-logger-pass"

创建一个启用 clickhouse-logger 的路由，如下所示：

curl "http://127.0.0.1:9180/apisix/admin/routes/clickhouse-logger-route" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "uri": "/anything/clickhouse",
    "plugins": {
      "clickhouse-logger": {
        "user": "apisix_logger",
        "password": "apisix-logger-pass",
        "database": "apisix_logs",
        "logtable": "default_logs",
        "endpoint_addrs": ["http://clickhouse-server:8123"]
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

向路由发送请求以生成日志条目：

curl -i "http://127.0.0.1:9080/anything/clickhouse"

你应该会看到一个 HTTP/1.1 200 OK 响应。

向 ClickHouse 发送请求以查看日志条目：

echo 'SELECT host, client_ip, route_id, start_time FROM apisix_logs.default_logs ORDER BY start_time DESC LIMIT 1 FORMAT PrettyCompactMonoBlock' | \
  curl "http://127.0.0.1:8123/?" \
  -u "apisix_logger:apisix-logger-pass" \
  --data-binary @-

你应该会看到类似以下的日志条目：

   ┌─host─┬─client_ip─────┬─route_id────────────────┬─start_time────┐
1. │      │ 192.168.155.1 │ clickhouse-logger-route │ 1789560520546 │
   └──────┴───────────────┴─────────────────────────┴───────────────┘

通过插件元数据自定义日志格式​

以下示例展示了如何使用插件元数据自定义日志格式。

在 ClickHouse 数据库中创建一个名为 custom_logs 的表，其列对应于你的自定义日志格式：

curl "http://127.0.0.1:8123" -X POST -d '
  CREATE TABLE apisix_logs.custom_logs (
    host String,
    client_ip String,
    route_id String,
    service_id String,
    `@timestamp` String,
    PRIMARY KEY(`@timestamp`)
  )
  ENGINE = MergeTree()
' -u "apisix_logger:apisix-logger-pass"

创建一个启用 clickhouse-logger 插件的路由，用于将指定格式的日志转发到 ClickHouse：

curl "http://127.0.0.1:9180/apisix/admin/routes/clickhouse-logger-route" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "uri": "/anything/clickhouse",
    "plugins": {
      "clickhouse-logger": {
        "user": "apisix_logger",
        "password": "apisix-logger-pass",
        "database": "apisix_logs",
        "logtable": "custom_logs",
        "endpoint_addrs": ["http://clickhouse-server:8123"]
      }
    },
    "upstream": {
      "type": "roundrobin",
      "nodes": {
        "httpbin.org:80": 1
      }
    }
  }'

配置 clickhouse-logger 的插件元数据：

curl "http://127.0.0.1:9180/apisix/admin/plugin_metadata/clickhouse-logger" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "log_format": {
      "host": "$host",
      "client_ip": "$remote_addr",
      "route_id": "$route_id",
      "service_id": "$service_id",
      "@timestamp": "$time_iso8601"
    }
  }'

向路由发送请求以生成日志条目：

curl -i "http://127.0.0.1:9080/anything/clickhouse"

你应该会看到一个 HTTP/1.1 200 OK 响应。

向 ClickHouse 发送请求以查看日志条目：

echo 'SELECT host, client_ip, route_id, `@timestamp` FROM apisix_logs.custom_logs ORDER BY `@timestamp` DESC LIMIT 1 FORMAT PrettyCompactMonoBlock' | \
  curl "http://127.0.0.1:8123/?" \
  -u "apisix_logger:apisix-logger-pass" \
  --data-binary @-

你应该会看到类似以下的日志条目：

   ┌─host──────┬─client_ip─────┬─route_id────────────────┬─@timestamp────────────────┐
1. │ 127.0.0.1 │ 192.168.155.1 │ clickhouse-logger-route │ 2026-09-16T12:09:05+00:00 │
   └───────────┴───────────────┴─────────────────────────┴───────────────────────────┘