Apache APISIX 集成 Splunk HEC 日志采集：splunk-hec-logging 插件完整配置指南-开发者社区

Apache APISIX 集成 Splunk HEC 日志采集：splunk-hec-logging 插件完整配置指南

【免费下载链接】apisixThe Cloud-Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/ap/apisix

导读

splunk-hec-logging是 Apache APISIX 内置的日志类插件，用于将网关处理请求产生的上下文信息序列化为 Splunk Event Data、单元/集成测试与批处理处理器文档，完整讲解插件的属性含义、批处理聚合机制、默认与自定义日志格式、Admin API 配置步骤、以及日志检索与插件删除方法，帮助你快速在生产环境落地 APISIX → Splunk 的日志链路。

插件工作原理概述

当splunk-hec-logging插件被启用后，APISIX 会在请求的日志阶段（log阶段）将请求上下文信息序列化为 Splunk Event Data 格式，并提交到批处理队列。当批量数据达到上限或缓冲区超时后，队列中的数据会被一次性推送到 Splunk HEC，从而避免高频提交带来的性能开销。

从源码看，该插件定义在 apisix/plugins/splunk-hec-logging.lua 中，核心逻辑分为三部分：

get_logger_entry：组装符合 Splunk Event 结构的日志条目（含time、source、sourcetype、host、event字段）；
send_to_splunk：通过resty.http以POST方式将批量条目发送到 HEC 端点，携带Authorization: Splunk <token>鉴权头；
_M.log：作为插件日志阶段入口，将条目交给批处理处理器统一调度。

插件源码中定义了默认条目来源与类型常量（splunk-hec-logging.lua 第 29-30 行）：

local DEFAULT_SPLUNK_HEC_ENTRY_SOURCE = "apache-apisix-splunk-hec-logging" local DEFAULT_SPLUNK_HEC_ENTRY_TYPE = "_json"

即每个日志条目默认携带"source": "apache-apisix-splunk-hec-logging"与"sourcetype": "_json"元数据，便于在 Splunk 中按 source/sourcetype 过滤检索。

Attributes 属性说明

插件的 Schema 定义在源码 splunk-hec-logging.lua 第 37-65 行，并通过batch_processor_manager:wrap_schema(schema)自动并入批处理相关参数。完整属性如下：

名称	必填	默认值	描述
endpoint	True	Splunk HEC 端点配置（对象类型）。
endpoint.uri	True	Splunk HEC 事件收集器 API 端点地址。
endpoint.token	True	Splunk HEC 认证 Token。
endpoint.channel	False	Splunk HEC 发送数据的 Channel 标识（用于 Indexer Acknowledgment 场景，详见 About HTTP Event Collector Indexer Acknowledgment）。
endpoint.timeout	False	10	向 Splunk HEC 发送数据的超时时间（秒），源码中`minimum = 1`，即最小为 1 秒。
ssl_verify	False	true	当为`true`时启用 SSL 校验（参考 OpenResty 文档中`tcpsock:sslhandshake`的行为）。
log_format	False	以 JSON 键值对形式声明的日志格式，值仅支持字符串；以`$`前缀的字符串可引用 APISIX 或 Nginx 变量。

值得注意的源码细节：endpoint.uri复用了core.schema.uri_def校验规则，因此必须是合法的 URI（测试用例中127.0.0.1:18088/services/collector这种缺少协议前缀的写法会校验失败）；endpoint对象强制要求uri与token两个字段（splunk-hec-logging.lua 第 56 行）。

除了插件级log_format，还可以通过插件 Metadata（plugin_metadata）全局配置日志格式，详见下文「Metadata 全局日志格式」小节。

批处理参数（Batch Processor 参数）

该插件支持通过批处理处理器聚合条目，避免频繁提交数据。插件将批处理参数直接合并进自身 Schema（源码通过batch_processor_manager:wrap_schema(schema)实现，见 batch-processor-manager.lua 第 37-49 行），因此你可以像配置普通插件属性一样，在 Route 的插件配置中直接指定以下参数：

名称	类型	必填	默认值	描述
name	string	否	插件名（此处为`splunk-hec-logging`）	批处理处理器唯一标识。
batch_max_size	integer	否	1000	每批最多发送的日志条数，达到上限后自动推送。
inactive_timeout	integer	否	5	缓冲区最大刷新间隔（秒），到期后无论条数是否达到上限都强制推送。
buffer_duration	integer	否	60	批内最旧条目的最大存活时间（秒），超过后必须处理该批。
max_retry_count	integer	否	0	出错时在移除条目前的最大重试次数。
retry_delay	integer	否	1	执行失败后延迟重试的秒数。

关于批处理参数的完整定义与设计说明，可参考仓库文档 docs/en/latest/batch-processor.md。其关键行为包括：

当batch_max_size = 1时，每条日志立即发送；
当batch_max_size > 1时，日志先聚合，直到达到条数上限或超时再统一推送；
官方建议将inactive_timeout设置得小于buffer_duration，以保证批量刷新的及时性。

默认日志格式示例

未配置log_format时，插件会使用默认的完整日志结构（由 log-util.lua 的get_full_log采集请求/响应上下文，再经插件组装为 Splunk Event 结构）。一个典型的默认日志条目如下：

{ "sourcetype": "_json", "time": 1704513555.392, "event": { "upstream": "127.0.0.1:1980", "request_url": "http://localhost:1984/hello", "request_query": {}, "request_size": 59, "response_headers": { "content-length": "12", "server": "APISIX/3.7.0", "content-type": "text/plain", "connection": "close" }, "response_status": 200, "response_size": 118, "latency": 108.00004005432, "request_method": "GET", "request_headers": { "connection": "close", "host": "localhost" } }, "source": "apache-apisix-splunk-hec-logging", "host": "localhost" }

对照源码 get_logger_entry 可以看到，默认条目由以下字段拼装而成：

time：ngx.now()获取的秒级时间戳（浮点）；
source/sourcetype：上述两个默认常量；
host：entry.server.hostname，即网关所在主机的主机名；
event：包含request_url、request_method、request_headers、request_query、request_size、response_headers、response_status、response_size、latency、upstream等请求生命周期关键指标。

Metadata 全局日志格式

除了在 Route 上配置插件级log_format，还可以通过配置插件 Metadata 来设置日志格式，可用配置项如下：

名称	类型	必填	默认值	描述
log_format	object	否	以 JSON 键值对声明的日志格式，值仅支持字符串；以`$`前缀可引用 APISIX 或 Nginx 变量。

:::info IMPORTANT 插件 Metadata 的配置是全局生效的，即会对所有使用了splunk-hec-logging插件的 Route 和 Service 同时生效。 :::

Metadata 的 Schema 定义在源码 splunk-hec-logging.lua 第 67-74 行，且check_schema会根据schema_type分别校验插件 Schema 与 Metadata Schema（第 85-91 行）。测试用例 TEST 6 还验证了log_format必须是 object 类型，传入字符串会返回400与错误信息wrong type: expected object, got string。

通过 Admin API 配置 Metadata

:::note 可以从config.yaml中获取admin_key并保存为环境变量，执行以下命令：

admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')

:::

curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/splunk-hec-logging -H "X-API-KEY: $admin_key" -X PUT -d ' { "log_format": { "host": "$host", "@timestamp": "$time_iso8601", "client_ip": "$remote_addr" } }'

使用上述配置后，日志会被格式化为如下形式：

[{"time":1673976669.269,"source":"apache-apisix-splunk-hec-logging","event":{"host":"localhost","client_ip":"127.0.0.1","@timestamp":"2023-01-09T14:47:25+08:00","route_id":"1"},"host":"DESKTOP-2022Q8F-wsl","sourcetype":"_json"}]

注意两点：

time、source、sourcetype仍由插件自动填充，event内容则替换为你自定义的键值对；
自定义格式下host字段取自core.utils.gethostname()（源码 splunk-hec-logging.lua 第 117 行）；
自定义格式解析由 log-util.lua 的get_custom_format_log完成：以$开头的值会被解析为 Nginx/APISIX 变量（如$host、$time_iso8601、$remote_addr），非$开头的值按普通字符串常量处理；同时该函数会自动附带route_id、service_id等路由信息。

启用插件

完整配置示例

以下示例展示了在指定 Route 上启用该插件的完整配置，同时覆盖 HEC 端点参数与批处理调优参数：

curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d ' { "plugins":{ "splunk-hec-logging":{ "endpoint":{ "uri":"http://127.0.0.1:8088/services/collector", "token":"BD274822-96AA-4DA6-90EC-18940FB2414C", "channel":"FE0ECFAD-13D5-401B-847D-77833BD77131", "timeout":60 }, "buffer_duration":60, "max_retry_count":0, "retry_delay":1, "inactive_timeout":2, "batch_max_size":10 } }, "upstream":{ "type":"roundrobin", "nodes":{ "127.0.0.1:1980":1 } }, "uri":"/splunk.do" }'

该配置中：endpoint.uri指向 HEC 的/services/collector路径，endpoint.token为 HEC 鉴权 Token，endpoint.channel用于 HEC Indexer Acknowledgment，endpoint.timeout为发送超时；批处理参数将每批条数限制为 10、缓冲区刷新间隔 2 秒、最长缓冲 60 秒、失败重试 0 次。

最小配置示例

只需提供endpoint.uri与endpoint.token即可启用插件，其余参数均使用默认值：

curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d ' { "plugins":{ "splunk-hec-logging":{ "endpoint":{ "uri":"http://127.0.0.1:8088/services/collector", "token":"BD274822-96AA-4DA6-90EC-18940FB2414C" } } }, "upstream":{ "type":"roundrobin", "nodes":{ "127.0.0.1:1980":1 } }, "uri":"/splunk.do" }'

发送逻辑的源码级说明

从源码 send_to_splunk 可以看到数据真正发出时的请求细节：

请求头固定携带Content-Type: application/json与Authorization: Splunk <token>（Token 拼在Splunk之后）；
若配置了channel，则额外携带X-Splunk-Request-Channel请求头；
批量条目逐条core.json.encode后直接拼接（无分隔符）作为请求体，这正是 HEC 批量写入的标准格式；
通过resty.http的request_uri发出POST请求，ssl_verify与超时均取自插件配置；
响应非 200 或请求失败时返回错误，错误信息交由批处理处理器记录并按其重试策略处理。

使用示例与日志检索

Route 配置完成后，向 APISIX 发起一个请求即可产生日志：

curl -i http://127.0.0.1:9080/splunk.do?q=hello

请求完成后，登录 Splunk 即可在搜索界面中检索到 APISIX 推送的日志：

仓库测试用例 t/plugin/splunk-hec-logging.t 使用ci/pod/vector模拟 HEC 接收端，完整覆盖了以下验证场景：

TEST 1：Schema 校验——完整配置、最小配置通过，缺uri/ 缺token/ 非法uri均报错；
TEST 2-3：使用错误 Token 发送时，错误日志中出现failed to send splunk, Invalid authorization与exceeded the max_retry_count；
TEST 4-5：正确 Token 下成功写入日志；
TEST 6-12：覆盖自定义log_format的元数据校验、Metadata 格式日志、Route 级格式日志以及批量数据（batch_max_size = 3）推送，并通过tail -n 1 ci/pod/vector/splunk.log断言日志确实落盘。

删除插件

如需移除splunk-hec-logging插件，只需将 Route 配置中对应插件的 JSON 配置删除。APISIX 会自动热加载新配置，无需重启即可生效：

curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d ' { "uri": "/hello", "plugins": {}, "upstream": { "type": "roundrobin", "nodes": { "127.0.0.1:1980": 1 } } }'

总结与最佳实践

综合官方文档、源码与测试，使用splunk-hec-logging插件时有几点值得注意：

必填项最小化：endpoint.uri与endpoint.token是启用插件的唯一硬性要求，其余参数均有默认值；
批量参数按流量调优：高并发场景可适当调大batch_max_size并保持inactive_timeout < buffer_duration，以平衡实时性与 HEC 写入压力；
日志格式按需定制：默认格式包含完整的请求/响应元数据；如需精简或补充字段（如 APISIX/Nginx 变量），优先使用 Metadata 全局配置或 Route 级log_format，注意 Metadata 为全局生效；
鉴权与安全：Token 通过Authorization: Splunk请求头发送，若 HEC 走 HTTPS，请务必保持ssl_verify为true并确保证书受信；
失败可观测：发送失败信息会进入 APISIX 错误日志（形如failed to send splunk, ...），配合max_retry_count可在网络抖动时提升写入成功率。