本文将为大家介绍如何在云原生 API 网关 Apache APISIX 中配置和使用 Splunk HEC 服务。
随着技术的不断迭代和企业架构的不断演进，系统的复杂度越来越高。日志作为分析和观测的“原材料”，能支持和兼容不同的分析引擎会为用户在选型和后期运维过程中降低很大成本。基于日志的分析和观测作为保障系统稳定的基石，它的角色非常重要。
Apache APISIX 作为一个高性能的 API 网关不仅在性能上有着良好的表现，并且在数据和日志的运维上通过和社区用户的交流共建也已经支持了大部分主流的开源及商业日志解决方案，包括：HTTP Logger 、TCP Logger、Kafka Logger、UDP Logger、RocketMQ Logger、SkyWalking Logger、Aliyun Cloud Logging（SLS）、Google Cloud Logging 等。
最近通过社区的共建支持，Apache APISIX 的 Logger 全家桶中又多了一位新成员：Splunk HEC Logging。
本文将为大家介绍如何在 Apache APISIX 中配置和使用 Splunk HEC 服务。
关于 Splunk HTTP Event Collector
Splunk 是一个机器数据的全文搜索引擎，可应用于采集、索引、搜索和分析各种应用数据，根据 DB Engines 的检索引擎排名，目前 Splunk 位列第二，是一款应用广泛的全文检索软件。Splunk 和 ElasticSearch 一样，是准实时可以提供不间断搜索结果的数据流。
Splunk HTTP Event Collector（HEC） 是 Splunk 提供的 HTTP 事件收集器，主要提供以 HTTP(S) 协议将数据和应用程序事件发送到 Splunk 的能力。
关于 Splunk HEC Logging 插件
splunk-hec-logging 插件用于将 Apache APISIX 的请求日志转发到 Splunk 中进行分析和存储。启用该插件后，Apache APISIX 将在 Log 阶段获取请求上下文信息，并将其序列化为 Splunk Event Data 格式后提交到批处理队列中。当触发批处理队列每批次最大处理容量，或刷新缓冲区的最大时间时，会将队列中的数据提交到 Splunk HEC 中。
如何使用 Splunk HEC Logging 插件
Splunk 配置步骤
部署 Splunk Enterprise
请参考 Splunk 的 官方安装指南 进行部署，本文将通过 Docker 进行部署演示。 Docker 命令参数如下：
docker run -p 18088:8088 -p 18000:8000 \ # 8088为HEC端口，8000为管理后台端口
-e "SPLUNK_PASSWORD=your-password" \ # 管理后台登录密码
-e "SPLUNK_START_ARGS=--accept-license" \ # 接受许可证条款（Splunk默认将提供一张Enterprise Trial License）
-e "SPLUNK_HEC_TOKEN=your-hec-token" \ # 设置默认HEC令牌，配置此项后将创建一个默认的HEC
-itd --rm --name splunk-example splunk/splunk:latest
命令参数具体释义可参考：Docker Splunk 文档。
配置 Splunk HEC
Docker 中已经配置并创建了默认的 HEC，在这里不再过多赘述创建 HEC 的流程。具体手动创建的流程可参考文档：Set up and use HTTP Event Collector in Splunk Web。
登录 Splunk Enterprise 并检查 HEC
通过浏览器访问 Docker 的映射端口。因为需要把管理后台的 8000 端口映射到宿主机的 18000 端口，所以在操作时可以在宿主机上通过「回环地址加端口」的方式在浏览器访问即可。例如：http://127.0.0.1:18000，登录的默认用户名是 admin，密码是在上例的环境变量中设置的 SPLUNK_PASSWORD 的值。
如下图所示，表示登录成功。
单击界面右上方 “Settings > Data Inputs” 检查默认 HEC 是否设置成功：
在 HTTP Event Collector 的 Inputs 列中我们已经可以看到 HEC 的数量，表示设置成功。
此时可以点击 HTTP Event Collector 进入 HEC 详情列表查看 HECs 的 Token 信息。
Token Values 即在上文中 Docker 环境变量中配置的 SPLUNK_HEC_TOKEN 的值。
Apache APISIX 配置步骤
启用插件
运行以下命令，启用 splunk-hec-logging 插件。
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"plugins":{
"splunk-hec-logging":{
"endpoint":{
// HEC 端点地址
"uri":"http://127.0.0.1:18088/services/collector",
// HEC Token
"token":"BD274822-96AA-4DA6-90EC-18940FB2414C"
},
// // 刷新批处理队列缓冲区的最大时间（以秒为单位）
"inactive_timeout":2,
// 每个批处理队列最大容纳日志条目数
"batch_max_size":10
}
},
"upstream":{
"type":"roundrobin",
"nodes":{
"127.0.0.1:1980":1
}
},
"uri":"/splunk.do"
}'
插件参数说明如下表所示。
| 名称 | 是否必填 | 默认值 | 描述 |
|---|---|---|---|
| endpoint | 是 | N/A | Splunk HEC 端点配置信息 |
| endpoint.uri | 是 | N/A | Splunk HEC 事件收集API |
| endpoint.token | 是 | N/A | Splunk HEC 身份令牌 |
| endpoint.channel | 否 | N/A | Splunk HEC 发送渠道标识，参考：About HTTP Event Collector Indexer Acknowledgment |
| endpoint.timeout | 否 | 10 | Splunk HEC 数据提交超时时间（以秒为单位） |
| ssl_verify | 否 | TRUE | 启用 SSL 验证， 参考：OpenResty 文档 |
| max_retry_count | 否 | 0 | 从处理管道中移除之前的最大重试次数 |
| retry_delay | 否 | 1 | 如果执行失败，流程执行应延迟的秒数 |
| buffer_duration | 否 | 60 | 必须先处理批次中最旧条目的最大期限（以秒为单位） |
| inactive_timeout | 否 | 5 | 刷新缓冲区的最大时间（以秒为单位） |
| batch_max_size | 否 | 1000 | 每个批处理队列可容纳的最大条目数 |
发送请求
运行以下命令，向 Splunk 发送请求。
$ curl -i http://127.0.0.1:9080/splink.do
HTTP/1.1 200 OK
Content-Type: text/html; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive
Date: Fri, 10 Dec 2021 09:57:52 GMT
Server: APISIX/2.11.0
Hello, Splunk HEC Logging
验证日志
登录 Splunk 控制台，点击 “Search & Reporting”。
在搜索输入框中输入：source="apache-apisix-splunk-hec-logging"，即可查询到发送的请求日志。
停用插件
移除 splunk-hec-logging 相关配置即可。
curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"uri":"/logging.do",
"upstream":{
"type":"roundrobin",
"nodes":{
"127.0.0.1:1980":1
}
},
"plugins":{
}
}'
总结
目前，Apache APISIX 也在开发其他插件以支持集成更多服务，如果您对此感兴趣，欢迎随时在 GitHub Discussion 中发起讨论，也可通过邮件列表进行交流。