splunk-hec-logging
splunk-hec-logging 插件将请求和响应上下文信息序列化为 Splunk 事件数据格式 并分批推送到 Splunk HTTP 事件收集器 (HEC)。该插件还支持自定义日志格式。
示例
以下示例展示了如何在不同场景下配置 splunk-hec-logging 插件。
要跟随示例操作，请完成以下步骤以设置 Splunk：
- Local Splunk
- Kubernetes
完成以下步骤以设置 Splunk：
- 安装 Splunk。默认情况下，Splunk Web 应在
localhost:8000上运行。 - 参阅在 Splunk Web 中设置和使用 HTTP Event Collector，创建 HTTP Event Collector。
- 导航到 Settings > Data Inputs，并记下 Token 值。
- 在 HTTP Event Collector > Global Settings 中启用所有 Token，并记下收集器端口；默认端口为
8088。
要验证设置，请使用你的令牌执行以下命令：
curl "http://localhost:8088/services/collector/event" \
-H "Authorization: Splunk <replace-with-your-token>" \
-d '{"event": "hello world"}'
你应该看到 success 响应。
创建 Kubernetes 清单以部署启用了 HEC 的 Splunk：
splunk-hec-server.yaml
apiVersion: v1
kind: ConfigMap
metadata:
namespace: aic
name: splunk-defaults
data:
default.yml: |
splunk:
hec:
enable: True
ssl: False
token: apisix-hec-token
---
apiVersion: apps/v1
kind: Deployment
metadata:
namespace: aic
name: splunk
spec:
replicas: 1
selector:
matchLabels:
app: splunk
template:
metadata:
labels:
app: splunk
spec:
enableServiceLinks: false
containers:
- name: splunk
image: splunk/splunk:9.4
env:
- name: SPLUNK_START_ARGS
value: "--accept-license"
# 接受 Splunk 通用条款：https://www.splunk.com/en_us/legal/splunk-general-terms.html
- name: SPLUNK_GENERAL_TERMS
value: "--accept-sgt-current-at-splunk-com"
- name: SPLUNK_PASSWORD
value: "Splunk@1234"
ports:
- containerPort: 8088
- containerPort: 8000
volumeMounts:
- name: defaults
mountPath: /tmp/defaults
readinessProbe:
httpGet:
path: /services/collector/health
port: 8088
initialDelaySeconds: 60
periodSeconds: 10
failureThreshold: 10
volumes:
- name: defaults
configMap:
name: splunk-defaults
---
apiVersion: v1
kind: Service
metadata:
namespace: aic
name: splunk-hec
spec:
selector:
app: splunk
ports:
- name: hec
port: 8088
targetPort: 8088
- name: web
port: 8000
targetPort: 8000
type: ClusterIP
应用清单：
kubectl apply -f splunk-hec-server.yaml
将 Splunk Web 端口转发到本机：
kubectl port-forward -n aic svc/splunk-hec 8000:8000
然后打开 http://localhost:8000，使用用户名 admin 和密码 Splunk@1234 登录。
推送日志到 Splunk
以下示例展示了如何在路由上启用 splunk-hec-logging 插件，该插件记录客户端请求并将日志推送到 Splunk。
创建一个路由如下：
- Admin API
- ADC
- Ingress Controller
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"id": "splunk-route",
"uri": "/anything",
"plugins": {
"splunk-hec-logging": {
"endpoint": {
"uri": "http://127.0.0.1:8088/services/collector/event",
"token": "example-splunk-hec-token"
}
}
},
"upstream": {
"nodes": {
"httpbin.org:80": 1
},
"type": "roundrobin"
}
}'
adc.yaml
services:
- name: httpbin
routes:
- name: splunk-route
uris:
- /anything
plugins:
splunk-hec-logging:
endpoint:
uri: http://127.0.0.1:8088/services/collector/event
token: example-splunk-hec-token
upstream:
type: roundrobin
nodes:
- host: httpbin.org
port: 80
weight: 1
将配置同步到网关：
adc sync -f adc.yaml
- Gateway API
- APISIX CRD
splunk-hec-logging-ic.yaml
apiVersion: v1
kind: Service
metadata:
namespace: aic
name: httpbin-external-domain
spec:
type: ExternalName
externalName: httpbin.org
---
apiVersion: apisix.apache.org/v1alpha1
kind: PluginConfig
metadata:
namespace: aic
name: splunk-hec-logging-plugin-config
spec:
plugins:
- name: splunk-hec-logging
config:
endpoint:
uri: http://splunk-hec.aic.svc.cluster.local:8088/services/collector/event
token: apisix-hec-token
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
namespace: aic
name: splunk-route
spec:
parentRefs:
- name: apisix
rules:
- matches:
- path:
type: Exact
value: /anything
filters:
- type: ExtensionRef
extensionRef:
group: apisix.apache.org
kind: PluginConfig
name: splunk-hec-logging-plugin-config
backendRefs:
- name: httpbin-external-domain
port: 80
splunk-hec-logging-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: splunk-route
spec:
ingressClassName: apisix
http:
- name: splunk-route
match:
paths:
- /anything
methods:
- GET
upstreams:
- name: httpbin-external-domain
plugins:
- name: splunk-hec-logging
enable: true
config:
endpoint:
uri: http://splunk-hec.aic.svc.cluster.local:8088/services/collector/event
token: apisix-hec-token
应用配置：
kubectl apply -f splunk-hec-logging-ic.yaml
❶ 配置 Splunk HTTP 收集器端点。对于 Kubernetes，请使用集群内 Service 地址，例如 http://splunk-hec.aic.svc.cluster.local:8088/services/collector/event。
❷ 替换为你的收集器令牌。
发送一些请求到该路由：
curl -i "http://127.0.0.1:9080/anything"
你应该收到 HTTP/1.1 200 OK 响应。
导航到 Splunk Web 并在左侧菜单中选择 Search & Reporting。在搜索框中输入 source="apache-apisix-splunk-hec-logging" 并搜索来自 APISIX 的事件。你应该看到与你的请求对应的事件，如下所示：
使用插件元数据记录请求和响应头
以下示例展示了如何使用 插件元数据 和 内置变量 自定义日志格式，以记录请头和响应头中的特定信息。
在 APISIX 中，插件元数据 用于配置同一插件的所有插件实例的通用元数据字段。当一个插件在多个资源中启用并需要统一更新其元数据字段时，这非常有用。
创建一个路由如下：
- Admin API
- ADC
- Ingress Controller
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"id": "splunk-route",
"uri": "/anything",
"plugins": {
"splunk-hec-logging": {
"endpoint": {
"uri": "http://127.0.0.1:8088/services/collector/event",
"token": "example-splunk-hec-token"
}
}
},
"upstream": {
"nodes": {
"httpbin.org:80": 1
},
"type": "roundrobin"
}
}'
adc.yaml
services:
- name: httpbin
routes:
- name: splunk-route
uris:
- /anything
plugins:
splunk-hec-logging:
endpoint:
uri: http://127.0.0.1:8088/services/collector/event
token: example-splunk-hec-token
upstream:
type: roundrobin
nodes:
- host: httpbin.org
port: 80
weight: 1
将配置同步到网关：
adc sync -f adc.yaml
- Gateway API
- APISIX CRD
splunk-hec-logging-ic.yaml
apiVersion: v1
kind: Service
metadata:
namespace: aic
name: httpbin-external-domain
spec:
type: ExternalName
externalName: httpbin.org
---
apiVersion: apisix.apache.org/v1alpha1
kind: PluginConfig
metadata:
namespace: aic
name: splunk-hec-logging-plugin-config
spec:
plugins:
- name: splunk-hec-logging
config:
endpoint:
uri: http://splunk-hec.aic.svc.cluster.local:8088/services/collector/event
token: apisix-hec-token
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
namespace: aic
name: splunk-route
spec:
parentRefs:
- name: apisix
rules:
- matches:
- path:
type: Exact
value: /anything
filters:
- type: ExtensionRef
extensionRef:
group: apisix.apache.org
kind: PluginConfig
name: splunk-hec-logging-plugin-config
backendRefs:
- name: httpbin-external-domain
port: 80
splunk-hec-logging-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: splunk-route
spec:
ingressClassName: apisix
http:
- name: splunk-route
match:
paths:
- /anything
methods:
- GET
upstreams:
- name: httpbin-external-domain
plugins:
- name: splunk-hec-logging
enable: true
config:
endpoint:
uri: http://splunk-hec.aic.svc.cluster.local:8088/services/collector/event
token: apisix-hec-token
应用配置：
kubectl apply -f splunk-hec-logging-ic.yaml
配置 splunk-hec-logging 的插件元数据：
- Admin API
- ADC
- Ingress Controller
curl "http://127.0.0.1:9180/apisix/admin/plugin_metadata/splunk-hec-logging" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"log_format": {
"host": "$host",
"@timestamp": "$time_iso8601",
"route_id": "$route_id",
"client_ip": "$remote_addr",
"env": "$http_env",
"resp_content_type": "$sent_http_Content_Type"
}
}'
adc.yaml
plugin_metadata:
- name: splunk-hec-logging
log_format:
host: "$host"
"@timestamp": "$time_iso8601"
route_id: "$route_id"
client_ip: "$remote_addr"
env: "$http_env"
resp_content_type: "$sent_http_Content_Type"
将配置同步到网关：
adc sync -f adc.yaml
- Gateway API
- APISIX CRD
gatewayproxy.yaml
apiVersion: apisix.apache.org/v1alpha1
kind: GatewayProxy
metadata:
namespace: aic
name: apisix-config
spec:
provider:
type: ControlPlane
controlPlane:
# ...
# 控制面连接配置
pluginMetadata:
splunk-hec-logging:
log_format:
host: "$host"
"@timestamp": "$time_iso8601"
route_id: "$route_id"
client_ip: "$remote_addr"
env: "$http_env"
resp_content_type: "$sent_http_Content_Type"
gatewayproxy.yaml
apiVersion: apisix.apache.org/v1alpha1
kind: GatewayProxy
metadata:
namespace: aic
name: apisix-config
spec:
provider:
type: ControlPlane
controlPlane:
# ...
# 控制面连接配置
pluginMetadata:
splunk-hec-logging:
log_format:
host: "$host"
"@timestamp": "$time_iso8601"
route_id: "$route_id"
client_ip: "$remote_addr"
env: "$http_env"
resp_content_type: "$sent_http_Content_Type"
应用配置：
kubectl apply -f gatewayproxy.yaml
❶ 记录自定义请求头 env。
❷ 记录响应头 Content-Type。
发送带有 env 头的请求到该路由：
curl -i "http://127.0.0.1:9080/anything" -H "env: dev"
导航到 Splunk Web 并在左侧菜单中选择 Search & Reporting。在搜索框中输入 source="apache-apisix-splunk-hec-logging" 并搜索事件。你应该看到最新的事件对应你的请求，类似于以下内容：