syslog
syslog 插件将 APISIX 和 API7 网关的请求及响应日志作为 JSON 对象分批发送到 Syslog 服务器。它支持 TCP、UDP、TLS 和自定义日志格式。
示例
以下示例展示如何把网关请求日志发送到 Syslog Collector、自定义日志内容，以及按条件记录请求体。
要跟随示例操作，请准备一个 Syslog Collector：
- Docker
- Kubernetes
固定版本的 rsyslog Collector 镜像仅发布 amd64 版本。设置正在运行的 APISIX 或 API7 网关容器名称：
export GATEWAY_CONTAINER=replace-with-gateway-container-name
创建专用网络：
docker network create gateway-rsyslog-net
将网关连接到该网络：
docker network connect gateway-rsyslog-net "$GATEWAY_CONTAINER"
启动已启用 TCP 接收的 Collector：
docker run -d \
--platform linux/amd64 \
--name rsyslog-collector \
--network gateway-rsyslog-net \
-e ENABLE_TCP=on \
-e ENABLE_UDP=off \
rsyslog/rsyslog-collector:2026-04
设置 APISIX Admin API 和 ADC 示例使用的 Collector 主机名：
export SYSLOG_HOST=rsyslog-collector
在另一个终端中跟踪 Collector 收到的日志：
docker exec rsyslog-collector tail -f /var/log/all.log
创建 Kubernetes 清单以部署 Collector：
syslog-server.yaml
apiVersion: apps/v1
kind: Deployment
metadata:
namespace: aic
name: rsyslog-collector
spec:
replicas: 1
selector:
matchLabels:
app: rsyslog-collector
template:
metadata:
labels:
app: rsyslog-collector
spec:
nodeSelector:
kubernetes.io/arch: amd64
containers:
- name: rsyslog-collector
image: rsyslog/rsyslog-collector:2026-04
env:
- name: ENABLE_TCP
value: "on"
- name: ENABLE_UDP
value: "off"
ports:
- name: syslog-tcp
containerPort: 514
protocol: TCP
readinessProbe:
tcpSocket:
port: syslog-tcp
initialDelaySeconds: 2
periodSeconds: 5
---
apiVersion: v1
kind: Service
metadata:
namespace: aic
name: rsyslog-collector
spec:
selector:
app: rsyslog-collector
ports:
- name: syslog-tcp
port: 514
targetPort: syslog-tcp
protocol: TCP
应用清单：
kubectl apply -f syslog-server.yaml
等待 Collector 就绪：
kubectl rollout status -n aic deployment/rsyslog-collector
设置 APISIX Admin API 和 ADC 示例使用的 Collector 主机名：
export SYSLOG_HOST=rsyslog-collector.aic.svc
在另一个终端中跟踪 Collector 收到的日志：
kubectl exec -n aic deploy/rsyslog-collector -- \
tail -f /var/log/all.log
将日志发送到 Syslog 服务器
以下示例在路由上启用 syslog 插件，并将匹配请求的日志发送到 Collector。
创建一个路由并在其上启用 syslog：
- APISIX Admin API
- ADC
- Ingress Controller (Kubernetes)
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d @- <<EOF
{
"id": "syslog-route",
"uri": "/anything",
"plugins": {
"syslog": {
"host": "$SYSLOG_HOST",
"port": 514,
"flush_limit": 1
}
},
"upstream": {
"nodes": {
"httpbin.org:80": 1
},
"type": "roundrobin"
}
}
EOF
adc.yaml
services:
- name: httpbin
labels:
docs-example: syslog-logging
routes:
- name: syslog-route
uris:
- /anything
plugins:
syslog:
host: "${SYSLOG_HOST}"
port: 514
flush_limit: 1
upstream:
type: roundrobin
nodes:
- host: httpbin.org
port: 80
weight: 1
预览带有示例标签的服务变更：
adc diff -f adc.yaml \
--include-resource-type service \
--label-selector docs-example=syslog-logging
同步已审查的变更：
adc sync -f adc.yaml \
--include-resource-type service \
--label-selector docs-example=syslog-logging
- Gateway API
- APISIX CRD
syslog-ic.yaml
apiVersion: v1
kind: Service
metadata:
namespace: aic
name: httpbin-external-domain
spec:
type: ExternalName
externalName: httpbin.org
ports:
- name: http
port: 80
targetPort: 80
---
apiVersion: apisix.apache.org/v1alpha1
kind: PluginConfig
metadata:
namespace: aic
name: syslog-plugin-config
spec:
plugins:
- name: syslog
config:
host: rsyslog-collector.aic.svc
port: 514
flush_limit: 1
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
namespace: aic
name: syslog-route
spec:
parentRefs:
- name: apisix
rules:
- matches:
- path:
type: Exact
value: /anything
filters:
- type: ExtensionRef
extensionRef:
group: apisix.apache.org
kind: PluginConfig
name: syslog-plugin-config
backendRefs:
- name: httpbin-external-domain
port: 80
syslog-ic.yaml
apiVersion: apisix.apache.org/v2
kind: ApisixUpstream
metadata:
namespace: aic
name: httpbin-external-domain
spec:
ingressClassName: apisix
externalNodes:
- type: Domain
name: httpbin.org
---
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
namespace: aic
name: syslog-route
spec:
ingressClassName: apisix
http:
- name: syslog-route
match:
paths:
- /anything
methods:
- GET
upstreams:
- name: httpbin-external-domain
plugins:
- name: syslog
enable: true
config:
host: rsyslog-collector.aic.svc
port: 514
flush_limit: 1
应用配置：
kubectl apply -f syslog-ic.yaml
❶ 配置网关可访问的 Collector 主机名。
❷ port: 替换为你的 syslog 服务器端口。
❸ flush_limit：设置为 1，以便立即将日志推送到 syslog 服务器。
发送一个请求到该路由：
curl -i "http://127.0.0.1:9080/anything"
你应该收到 HTTP/1.1 200 OK 响应。
在 Collector 日志中，JSON 消息应包含类似以下字段：
{
"upstream": "100.31.16.17:80",
"service_id": "",
"client_ip": "192.168.155.1",
"response": {
"headers": {
"date": "Mon, 21 Sep 2026 09:44:46 GMT",
"content-type": "application/json",
"access-control-allow-origin": "*",
"server": "APISIX/3.18.0",
"access-control-allow-credentials": "true",
"connection": "close",
"content-length": "399"
},
"size": 627,
"status": 200
},
"start_time": 1789983884322,
"apisix_latency": 650.00001144409,
"latency": 1513.0000114441,
"upstream_latency": 863,
"request": {
"size": 85,
"uri": "/anything",
"headers": {
"x-forwarded-proto": "http",
"user-agent": "curl/8.7.1",
"accept": "*/*",
"host": "127.0.0.1:9080",
"x-forwarded-port": "9080",
"x-forwarded-host": "127.0.0.1:9080"
},
"querystring": {},
"url": "http://127.0.0.1:9080/anything",
"method": "GET"
},
"route_id": "syslog-route",
"server": {
"version": "3.18.0",
"hostname": "dd2886d0b7bf"
}
}
使用插件元数据添加字段
以下示例使用插件元数据和内置变量，为未自行定义 log_format_extra 的 syslog 实例添加选定的请求和响应字段。
创建一个启用 syslog 插件的路由：
- APISIX Admin API
- ADC
- Ingress Controller (Kubernetes)
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d @- <<EOF
{
"id": "syslog-route",
"uri": "/anything",
"plugins": {
"syslog": {
"host": "$SYSLOG_HOST",
"port": 514,
"flush_limit": 1
}
},
"upstream": {
"nodes": {
"httpbin.org:80": 1
},
"type": "roundrobin"
}
}
EOF
adc.yaml
services:
- name: httpbin
labels:
docs-example: syslog-logging
routes:
- name: syslog-route
uris:
- /anything
plugins:
syslog:
host: "${SYSLOG_HOST}"
port: 514
flush_limit: 1
upstream:
type: roundrobin
nodes:
- host: httpbin.org
port: 80
weight: 1
预览带有示例标签的服务变更：
adc diff -f adc.yaml \
--include-resource-type service \
--label-selector docs-example=syslog-logging
同步已审查的变更：
adc sync -f adc.yaml \
--include-resource-type service \
--label-selector docs-example=syslog-logging
- Gateway API
- APISIX CRD
syslog-ic.yaml
apiVersion: v1
kind: Service
metadata:
namespace: aic
name: httpbin-external-domain
spec:
type: ExternalName
externalName: httpbin.org
ports:
- name: http
port: 80
targetPort: 80
---
apiVersion: apisix.apache.org/v1alpha1
kind: PluginConfig
metadata:
namespace: aic
name: syslog-plugin-config
spec:
plugins:
- name: syslog
config:
host: rsyslog-collector.aic.svc
port: 514
flush_limit: 1
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
namespace: aic
name: syslog-route
spec:
parentRefs:
- name: apisix
rules:
- matches:
- path:
type: Exact
value: /anything
filters:
- type: ExtensionRef
extensionRef:
group: apisix.apache.org
kind: PluginConfig
name: syslog-plugin-config
backendRefs:
- name: httpbin-external-domain
port: 80
syslog-ic.yaml
apiVersion: apisix.apache.org/v2
kind: ApisixUpstream
metadata:
namespace: aic
name: httpbin-external-domain
spec:
ingressClassName: apisix
externalNodes:
- type: Domain
name: httpbin.org
---
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
namespace: aic
name: syslog-route
spec:
ingressClassName: apisix
http:
- name: syslog-route
match:
paths:
- /anything
methods:
- GET
upstreams:
- name: httpbin-external-domain
plugins:
- name: syslog
enable: true
config:
host: rsyslog-collector.aic.svc
port: 514
flush_limit: 1
应用配置：
kubectl apply -f syslog-ic.yaml
配置 syslog 的插件元数据：
- APISIX Admin API
- ADC
- Ingress Controller (Kubernetes)
curl "http://127.0.0.1:9180/apisix/admin/plugin_metadata/syslog" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"log_format_extra": {
"host": "$host",
"@timestamp": "$time_iso8601",
"route_id": "$route_id",
"client_ip": "$remote_addr",
"resp_content_type": "$sent_http_Content_Type"
}
}'
插件元数据是全局集合，无法通过标签选择器隔离。修改该条目前，请先导出完整集合：
adc dump -o adc-metadata.yaml --with-id \
--include-resource-type plugin_metadata
在保留 adc-metadata.yaml 中所有其他条目的同时，添加或更新 syslog 条目：
adc-metadata.yaml（plugin_metadata 节选）
plugin_metadata:
# 保留导出文件中的所有其他插件元数据条目。
syslog:
log_format_extra:
host: "$host"
"@timestamp": "$time_iso8601"
route_id: "$route_id"
client_ip: "$remote_addr"
resp_content_type: "$sent_http_Content_Type"
预览完整的元数据变更，并确认其中没有非预期的更新或删除：
adc diff -f adc-metadata.yaml \
--include-resource-type plugin_metadata
同步已审查的插件元数据集合：
adc sync -f adc-metadata.yaml \
--include-resource-type plugin_metadata
在部署使用的完整 GatewayProxy 清单的 spec.pluginMetadata 下添加以下条目：
syslog:
log_format_extra:
host: "$host"
"@timestamp": "$time_iso8601"
route_id: "$route_id"
client_ip: "$remote_addr"
resp_content_type: "$sent_http_Content_Type"
通过该部署常规的 Kubernetes 或 GitOps 工作流应用更新后的完整清单。
发送一个请求到该路由：
curl -i "http://127.0.0.1:9080/anything"
在 Collector 日志中，JSON 消息应包含类似以下字段：
{
"@timestamp": "2026-04-17T05:39:46+00:00",
"resp_content_type": "application/json",
"host": "127.0.0.1",
"route_id": "syslog-route",
"client_ip": "192.168.155.1"
}
有条件地记录请求体
以下示例仅在查询参数满足配置的表达式时记录请求体。
创建一个启用 syslog 插件的路由如下：
- APISIX Admin API
- ADC
- Ingress Controller (Kubernetes)
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d @- <<EOF
{
"id": "syslog-route",
"uri": "/anything",
"plugins": {
"syslog": {
"host": "$SYSLOG_HOST",
"port": 514,
"flush_limit": 1,
"include_req_body": true,
"include_req_body_expr": [["arg_log_body", "==", "yes"]]
}
},
"upstream": {
"nodes": {
"httpbin.org:80": 1
},
"type": "roundrobin"
}
}
EOF
adc.yaml
services:
- name: httpbin
labels:
docs-example: syslog-logging
routes:
- name: syslog-route
uris:
- /anything
plugins:
syslog:
host: "${SYSLOG_HOST}"
port: 514
flush_limit: 1
include_req_body: true
include_req_body_expr:
- - arg_log_body
- ==
- "yes"
upstream:
type: roundrobin
nodes:
- host: httpbin.org
port: 80
weight: 1
预览带有示例标签的服务变更：
adc diff -f adc.yaml \
--include-resource-type service \
--label-selector docs-example=syslog-logging
同步已审查的变更：
adc sync -f adc.yaml \
--include-resource-type service \
--label-selector docs-example=syslog-logging
- Gateway API
- APISIX CRD
syslog-ic.yaml
apiVersion: v1
kind: Service
metadata:
namespace: aic
name: httpbin-external-domain
spec:
type: ExternalName
externalName: httpbin.org
ports:
- name: http
port: 80
targetPort: 80
---
apiVersion: apisix.apache.org/v1alpha1
kind: PluginConfig
metadata:
namespace: aic
name: syslog-plugin-config
spec:
plugins:
- name: syslog
config:
host: rsyslog-collector.aic.svc
port: 514
flush_limit: 1
include_req_body: true
include_req_body_expr:
- - arg_log_body
- ==
- "yes"
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
namespace: aic
name: syslog-route
spec:
parentRefs:
- name: apisix
rules:
- matches:
- path:
type: Exact
value: /anything
filters:
- type: ExtensionRef
extensionRef:
group: apisix.apache.org
kind: PluginConfig
name: syslog-plugin-config
backendRefs:
- name: httpbin-external-domain
port: 80
syslog-ic.yaml
apiVersion: apisix.apache.org/v2
kind: ApisixUpstream
metadata:
namespace: aic
name: httpbin-external-domain
spec:
ingressClassName: apisix
externalNodes:
- type: Domain
name: httpbin.org
---
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
namespace: aic
name: syslog-route
spec:
ingressClassName: apisix
http:
- name: syslog-route
match:
paths:
- /anything
methods:
- POST
upstreams:
- name: httpbin-external-domain
plugins:
- name: syslog
enable: true
config:
host: rsyslog-collector.aic.svc
port: 514
flush_limit: 1
include_req_body: true
include_req_body_expr:
- - arg_log_body
- ==
- "yes"
应用配置：
kubectl apply -f syslog-ic.yaml
❶ include_req_body：设置为 true 以包含请求体。
❷ include_req_body_expr：仅当 URL 查询字符串 log_body 为 yes 时包含请求体。在基于 YAML 的配置中，请用引号括起 "yes"，以避免 YAML 将其转换为布尔值。
发送一个满足条件的请求到该路由：
curl -i "http://127.0.0.1:9080/anything?log_body=yes" -X POST \
-H "Content-Type: application/json" \
-d '{"env":"dev"}'
你应该看到请求体被记录：
{
"upstream": "52.71.230.193:80",
"service_id": "",
"client_ip": "192.168.155.1",
"response": {
"headers": {
"date": "Mon, 21 Sep 2026 09:19:41 GMT",
"content-type": "application/json",
"access-control-allow-origin": "*",
"access-control-allow-credentials": "true",
"server": "APISIX/3.18.0",
"connection": "close",
"content-length": "543"
},
"size": 771,
"status": 200
},
"start_time": 1789982377612,
"apisix_latency": 2.0000038146973,
"latency": 3921.0000038147,
"upstream_latency": 3919,
"request": {
"size": 164,
"body": "{\"env\":\"dev\"}",
"uri": "/anything?log_body=yes",
"headers": {
"x-forwarded-port": "9080",
"content-type": "application/json",
"x-forwarded-proto": "http",
"user-agent": "curl/8.7.1",
"accept": "*/*",
"host": "127.0.0.1:9080",
"x-forwarded-host": "127.0.0.1:9080",
"content-length": "13"
},
"querystring": {
"log_body": "yes"
},
"url": "http://127.0.0.1:9080/anything?log_body=yes",
"method": "POST"
},
"route_id": "syslog-route",
"server": {
"version": "3.18.0",
"hostname": "dd2886d0b7bf"
}
}
发送一个不带 URL 查询字符串的请求到该路由：
curl -i "http://127.0.0.1:9080/anything" -X POST \
-H "Content-Type: application/json" \
-d '{"env":"dev"}'
你不应该在日志中看到请求体。
信息
上文使用的 log_format_extra 会保留默认日志条目，包括插件收集的请求体和响应体。如果改为配置 log_format，请显式包含对应变量：
{
"include_req_body": true,
"include_resp_body": true,
"log_format": {
"request_body": "$request_body",
"response_body": "$resp_body"
}
}
请求体和响应体大小限制仍然适用。如需在不替换默认日志条目的情况下添加自定义字段，请使用 log_format_extra。