记录 API 流量日志
API7 企业版可以记录路由的访问日志,包括主机、客户端 IP 地址和请求时间戳等信息。你可以使用这些日志定位和排查问题。
API7 企业版通过插件系统与多种日志平台集成,提供以下开箱即用的集成方式。
- HTTP/TCP/UDP 日志服务器
- SkyWalking
- Kafka
- RocketMQ
- ClickHouse
- Syslog
- 阿里云 SLS
- Google Cloud 日志服务
- Splunk HTTP Event Collector (HEC)
- 文件日志
- Elasticsearch
- 腾讯云 CLS
- Grafana Loki
本教程介绍如何配置 clickhouse-logger 插件,将 API 流量日志写入 ClickHouse 数据库。
前提条件
启动 ClickHouse 服务器
- Docker
- Kubernetes
在 Docker 中启动名为 quickstart-clickhouse-server 的 ClickHouse 实例,使用默认数据库 quickstart_db、默认用户 quickstart-user 和密码 quickstart-pass。
docker run -d \
--name quickstart-clickhouse-server \
--network=api7-ee_api7 \
-e CLICKHOUSE_DB=quickstart_db \
-e CLICKHOUSE_USER=quickstart-user \
-e CLICKHOUSE_PASSWORD=quickstart-pass \
-e CLICKHOUSE_DEFAULT_ACCESS_MANAGEMENT=1 \
--ulimit nofile=262144:262144 \
clickhouse/clickhouse-server
在本地或 Docker 中使用命令行工具 clickhouse-client 连接到 ClickHouse 实例。
docker exec -it quickstart-clickhouse-server clickhouse-client
在 quickstart_db 数据库中创建 test 表。示例中的 host、client_ip、route_id 和 @timestamp 字段均为 String 类型,你也可以按需调整。
CREATE TABLE quickstart_db.test (
`host` String,
`client_ip` String,
`route_id` String,
`@timestamp` String,
PRIMARY KEY(`@timestamp`)
) ENGINE = MergeTree()
操作成功后,输出会显示 Ok。
输入 exit 退出 Docker 容器。
安装 ClickHouse Operator
如果你已在 Kubernetes 上安装网关实例,并使用 Ingress Controller 管理配置,请安装 ClickHouse Operator。
curl -s "https://raw.githubusercontent.com/Altinity/clickhouse-operator/master/deploy/operator-web-installer/clickhouse-operator-install.sh" | OPERATOR_NAMESPACE=<YOUR_NAMESPACE> bash
检查所有资源。
kubectl get all
你应该能看到以下 ClickHouse Operator 资源。
NAME READY STATUS RESTARTS AGE
pod/clickhouse-operator-56c57f989-kjqtn 2/2 Running 0 32m
NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE
service/clickhouse-operator-metrics ClusterIP 10.96.253.156 <none> 8888/TCP,9999/TCP 32m
NAME READY UP-TO-DATE AVAILABLE AGE
deployment.apps/clickhouse-operator 1/1 1 1 32m
NAME DESIRED CURRENT READY AGE
replicaset.apps/clickhouse-operator-56c57f989 1 1 1 32m
安装 ClickHouse 服务器
创建一个单分片、单副本的安装清单文件。
apiVersion: clickhouse.altinity.com/v1
kind: ClickHouseInstallation
metadata:
name: clickhouse-installation
# namespace: api7 # replace with your namespace
spec:
configuration:
users:
test_user/password_sha256_hex: c019743ba8bc32d17800bca6d36de903feff9854897c61b6e63ce3e5e93c37ca
test_user/password: quickstart-pass
test_user/networks/ip:
- 0.0.0.0/0
clusters:
- name: simple
将配置应用到集群。
kubectl apply -f clickhouse-installation.yaml
检查正在运行的 Pod。
kubectl get pod
你应该能看到 ClickHouse 服务器的 Pod 正在运行。
NAME READY STATUS RESTARTS AGE
chi-clickhouse-installation-simple-0-0-0 1/1 Running 0 11m
配置 ClickHouse 服务器
连接到 ClickHouse 实例。
kubectl exec -it chi-clickhouse-installation-simple-0-0-0 -- clickhouse-client
创建数据库。
CREATE DATABASE quickstart_db
在 quickstart_db 数据库中创建 test 表。示例中的 host、client_ip、route_id 和 @timestamp 字段均为 String 类型,你也可以按需调整。
CREATE TABLE quickstart_db.test (
`host` String,
`client_ip` String,
`route_id` String,
`@timestamp` String,
PRIMARY KEY(`@timestamp`)
) ENGINE = MergeTree()
操作成功后,输出会显示 Ok。
输入 exit 退出 ClickHouse 服务器。
为所有服务配置日志记录
强烈建议通过全局规则启用日志插件,以便记录所有服务和路由的流量。
- 控制台
- ADC
- Ingress Controller
- 从侧边栏选择网关组的插件设置。
- 选择插件全局规则选项卡,然后点击启用插件。
- 在插件字段中搜索
clickhouse-logger插件,然后点击启用。 - 在对话框中完成以下操作。
-
将以下配置添加到 JSON 编辑器。
{"log_format": {"host": "$host","@timestamp": "$time_iso8601","client_ip": "$remote_addr"},"user": "quickstart-user","password": "quickstart-pass","database": "quickstart_db","logtable": "test","endpoint_addrs": ["http://quickstart-clickhouse-server:8123"]} -
点击启用。
要使用 ADC 启用日志记录,请创建以下配置。
global_rules:
clickhouse-logger:
_meta:
disable: false
database: quickstart_db
endpoint_addrs:
- http://quickstart-clickhouse-server:8123
log_format:
"@timestamp": $time_iso8601
client_ip: $remote_addr
host: $host
logtable: test
password: quickstart-pass
user: quickstart-user
将配置同步到 API7 企业版。
adc sync -f adc.yaml
ADC 以配置文件为唯一依据。运行 adc sync 时,请确保通过 -f 传入所有配置文件。
创建清单文件,为所有路由全局启用 clickhouse-logger 插件。
apiVersion: apisix.apache.org/v2
kind: ApisixGlobalRule
metadata:
name: global-observability
# namespace: api7 # replace with your namespace
spec:
plugins:
- name: clickhouse-logger
enable: true
config:
endpoint_addr: http://clickhouse-clickhouse-installation.api7.svc.cluster.local:8123
user: quickstart-user
password: quickstart-pass
logtable: test
database: quickstart_db
log_format:
"@timestamp": $time_iso8601
client_ip: $remote_addr
host: $host
将配置应用到集群。
kubectl apply -f global-observability.yaml
验证
向路由发送请求,生成一条访问日志。
curl -i "http://127.0.0.1:9080/ip"
- Docker
- Kubernetes
使用 Docker 中的命令行工具 clickhouse-client 连接到 ClickHouse 数据库。
docker exec -it quickstart-clickhouse-server clickhouse-client
连接到 ClickHouse 数据库。
kubectl exec -it chi-clickhouse-installation-simple-0-0-0 -- clickhouse-client
查询 quickstart_db.test 表中的所有记录。
SELECT * from quickstart_db.test
你应该能看到类似以下示例的访问日志。
┌─host───────────┬─client_ip────┬─route_id─────────────────────────────┬─@timestamp────────────────┐
│ 127.0.0.1 │ 192.168.2.10 │ f4a6ec82-5b9d-4c2d-9d36-2d3a7cf1c3b4 │ 2024-07-18T19:24:16+00:00 │
└────────────────┴──────────────┴──────────────────────────────────────┴───────────────────────────┘