Apache APISIX syslog 插件详解:将网关访问日志以 RFC 5424 格式推送到 Syslog 服务器

发布时间:2026/9/15 18:23:24

Apache APISIX syslog 插件详解:将网关访问日志以 RFC 5424 格式推送到 Syslog 服务器 Apache APISIX syslog 插件详解将网关访问日志以 RFC 5424 格式推送到 Syslog 服务器【免费下载链接】apisixThe Cloud-Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/ap/apisixsyslog是 Apache APISIX 内置的日志类插件负责在网关的 log 阶段把请求/响应访问日志聚合后发送到标准 Syslog 服务器并内置 RFC 5424 协议封装能力支持 TCP/UDP/TLS 传输。阅读本文后你将掌握 syslog 插件的全部配置属性、批量处理器参数、自定义日志格式log_format的使用方法并能通过 Admin API 完成插件的启用、测试与删除全流程。插件描述与适用场景syslog插件可用于将 APISIX 网关产生的日志推送到 Syslog 服务器如 rsyslog、syslog-ng 或各类日志采集器常用于将网关访问日志接入企业统一的 Syslog 日志中心进行集中存储与审计与 SIEM安全信息和事件管理系统对接实现基于 Syslog 的日志分析通过 TCP 或 UDP 将日志转发给轻量级采集器本项目测试环境使用 Vector 监听 5140/5150 端口接收 TCP/UDP Syslog 数据见 vector.toml。该插件不仅支持原生 Syslog 协议还实现了将日志数据以 JSON 格式发送到 Syslog 服务的能力插件先把访问日志序列化为 JSON再按 RFC 5424 格式封装成标准 Syslog 报文发送。从源码结构看插件由两部分组成syslog.lua插件入口定义 schema、在log阶段收集日志条目、在body_filter阶段收集请求/响应体syslog/init.lua底层实现负责 RFC 5424 编码、批量处理与 socket 发送。插件属性详解启用插件时支持以下属性与 syslog.lua 中的 schema 定义一一对应名称类型必选项默认值有效值描述hoststring是Syslog 服务器的 IP 地址或主机名。portinteger是目标上游端口Syslog 服务监听端口。namestring否sys logger标识 logger 的唯一标识符。如果使用 Prometheus 监控 APISIX 指标名称将以apisix_batch_process_entries导出。timeoutinteger否3000[1, ...]上游发送数据超时时间毫秒。tlsboolean否false当设置为true时执行 SSL 验证。flush_limitinteger否4096[1, ...]如果缓冲的消息大小加上当前消息大小达到≥此限制字节缓冲的日志消息将被写入日志服务器默认为 40964KB。drop_limitinteger否1048576如果缓冲的消息大小加上当前消息大小大于此限制字节由于缓冲区大小有限当前日志消息将被丢弃默认为 10485761MB。sock_typestring否tcp[tcp,udp]传输层使用的 IP 协议类型。max_retry_countinteger否[1, ...]连接日志服务器失败或发送日志消息失败后的最大重试次数。retry_delayinteger否[0, ...]重试连接或重试发送日志消息之前的时间延迟毫秒。pool_sizeinteger否5[5, ...]sock:keepalive使用的 keepalive 连接池大小。log_formatobject否以 JSON 键值对声明日志格式值部分仅支持字符串以$开头表示获取 APISIX 变量 或 NGINX 内置变量。include_req_bodyboolean否false[false, true]当设置为true时包含请求体。include_req_body_exprarray否当include_req_body为true时的过滤器仅当此处表达式求值为true时才记录请求体基于 lua-resty-expr 表达式。include_resp_bodyboolean否false[false, true]当设置为true时包含响应体。include_resp_body_exprarray否当include_resp_body为true时过滤响应体仅当表达式求值为true时才记录响应体。源码要点host与port为必填项缺少任一字段都会导致 schema 校验失败测试用例 t/plugin/syslog.t 中验证了缺少port时报property port is required传入字符串类型port时报wrong type: expected integer, got stringcheck_schema中会对tls字段做布尔类型兼容检查core.utils.check_tls_bool允许字符串形式的布尔值插件优先级为401见 syslog.lua在 log 阶段执行。批量处理器Batch Processor参数该插件支持使用批处理器聚合并批量处理日志条目避免插件频繁提交数据。默认情况下批处理器每5秒或队列中数据达到1000条时提交一次数据对应inactive_timeout 5与batch_max_size 1000定义见 batch-processor.lua。批处理参数通过插件配置直接生效由 batch-processor-manager.lua 的add_entry_to_new_processor透传给批处理器完整参数如下名称类型默认值有效值描述namestringsys logger用于标识批处理器的唯一标识符。batch_max_sizeinteger1000[1, ...]每批发送日志的最大条数达到该值即自动推送全部日志。inactive_timeoutinteger5[1, ...]刷新缓冲区的最大时间秒超时后无论条数是否达到上限都会推送。buffer_durationinteger60[1, ...]必须先处理批次中最旧条目的最长期限秒。max_retry_countinteger0[0, ...]从处理管道移除前的最大重试次数。retry_delayinteger1[0, ...]执行失败后延迟执行的秒数。实践建议保持inactive_timeout小于buffer_duration以获得最佳的批量刷新效果。若需每请求立即发送可将batch_max_size设为 1测试用例 t/plugin/syslog.t 即采用此配置做即时验证。完整说明参见 批处理器文档。默认日志格式示例当请求命中启用 syslog 插件的路由后日志条目会先被序列化为 JSON再封装为 RFC 5424 报文。默认日志格式示例如下461 2024-01-06T02:30:59.145Z 127.0.0.1 apisix 82324 - - {\response\:{\status\:200,\size\:141,\headers\:{\content-type\:\text/plain\,\server\:\APISIX/3.7.0\,\transfer-encoding\:\chunked\,\connection\:\close\}},\route_id\:\1\,\server\:{\hostname\:\baiyundeMacBook-Pro.local\,\version\:\3.7.0\},\request\:{\uri\:\/opentracing\,\url\:\http://127.0.0.1:1984/opentracing\,\querystring\:{},\method\:\GET\,\size\:155,\headers\:{\content-type\:\application/x-www-form-urlencoded\,\host\:\127.0.0.1:1984\,\user-agent\:\lua-resty-http/0.16.1 (Lua) ngx_lua/10025\}},\upstream\:\127.0.0.1:1982\,\apisix_latency\:100.99999809265,\service_id\:\\,\upstream_latency\:1,\start_time\:1704508259044,\client_ip\:\127.0.0.1\,\latency\:101.99999809265}\n对报文逐段拆解46Priority 值由 FacilitySYSLOG5× 8 SeverityINFO6 46 计算得出见 rfc5424.lua1RFC 5424 版本号2024-01-06T02:30:59.145ZRFC 3339 格式的 Zulu 时间戳127.0.0.1hostname取自ctx.var.hostapisixappname固定为apisix82324PID取自ctx.var.pid-结构化数据段本插件未启用 structured data末尾 JSON 部分完整的 APISIX 访问日志条目包含response、request、upstream、route_id、client_ip、latency、apisix_latency、start_time等字段。日志条目中的字段由 syslog.lua 调用log_util.get_log_entry生成编码逻辑在 syslog/init.lua 中完成。插件元数据与自定义日志格式除了在路由级别通过log_format属性定制日志格式外还可以通过插件元数据全局配置log_format名称类型必选项默认值描述log_formatobject否以 JSON 键值对声明日志格式值仅支持字符串以$开头表示获取 APISIX 变量 或 NGINX 内置变量。:::info 重要 该设置全局生效。如果指定了log_format则所有绑定syslog插件的路由或服务都将使用该日志格式。 :::使用插件元数据配置自定义日志格式的示例对应测试用例 t/plugin/syslog.tcurl http://127.0.0.1:9180/apisix/admin/plugin_metadata/syslog \ -H X-API-KEY: $admin_key -X PUT -d { log_format: { host: $host, client_ip: $remote_addr, upstream: $upstream_addr } }在路由级配置中log_format则只作用于该路由测试用例 t/plugin/syslog.t 演示了在路由内定义vip: $remote_addr后日志条目中出现vip字段。启用插件可以通过 Admin API 在指定路由上启用 syslog 插件。首先从config.yaml中获取admin_key并存入环境变量admin_key$(yq .deployment.admin.admin_key[0].key conf/config.yaml | sed s///g)然后向路由 1 下发启用配置curl http://127.0.0.1:9180/apisix/admin/routes/1 \ -H X-API-KEY: $admin_key -X PUT -d { plugins: { syslog: { host : 127.0.0.1, port : 5044, flush_limit : 1 } }, upstream: { type: roundrobin, nodes: { 127.0.0.1:1980: 1 } }, uri: /hello }说明上例将flush_limit设为 1表示消息大小达到 1 字节即触发刷新便于快速看到日志效果生产环境建议使用默认值 4096 以提升吞吐端口 5044 为示例目标端口实际应填写你部署的 Syslog 服务监听端口本项目测试环境在 vector.toml 中配置 TCP 监听 5140、UDP 监听 5150 用于接收 syslog 报文若需走 UDP 传输额外设置sock_type: udp测试用例 t/plugin/syslog.t 验证了 UDP 模式若需 TLS 加密传输设置tls: true连接池参数pool_size控制 keepalive 连接数。测试插件配置下发后向 APISIX 发起请求验证curl -i http://127.0.0.1:9080/helloHTTP/1.1 200 OK ... hello, world请求正常返回后检查 Syslog 服务器是否收到对应报文。在本项目的测试环境中报文会落盘到 Vector 的输出文件测试用例通过tail -n 1 ci/pod/vector/syslog-tcp.log校验日志内容见 t/plugin/syslog.t同时 error log 中会出现sending a batch logs to 127.0.0.1:port的发送记录见 syslog/init.lua。收集请求体与响应体如需在日志中包含请求体或响应体可开启对应开关include_req_body: true记录请求体。测试用例 t/plugin/syslog.t 验证了 POST{sample_payload:hello}后日志中出现body:{\sample_payload\:\hello\}include_resp_body: true记录响应体。测试用例 t/plugin/syslog.t 验证了日志中出现body:hello world\n配合include_req_body_expr/include_resp_body_expr可基于 lua-resty-expr 表达式按条件过滤仅当表达式求值为true时才记录对应 body。开启后插件通过body_filter阶段调用log_util.collect_body采集 body 数据见 syslog.lua。删除插件需要删除插件时通过 Admin API 更新路由配置将plugins置为空对象即可。APISIX 会自动重新加载相关配置无需重启服务curl http://127.0.0.1:9180/apisix/admin/routes/1 \ -H X-API-KEY: $admin_key -X PUT -d { methods: [GET], uri: /hello, plugins: {}, upstream: { type: roundrobin, nodes: { 127.0.0.1:1980: 1 } } }底层实现与工作链路从源码角度梳理 syslog 插件的完整工作链路schema 校验Admin API 下发配置时syslog.lua 的check_schema调用core.schema.check校验插件 schema并通过batch_processor_manager:wrap_schema注入批处理器参数batch_max_size、inactive_timeout、buffer_duration、max_retry_count、retry_delay等见 batch-processor-manager.luabody 采集body_filter阶段通过log_util.collect_body按需收集请求体/响应体日志生成log阶段调用log_util.get_log_entry生成完整日志条目含route_id、client_ip、latency、upstream等字段RFC 5424 封装push_entry先将条目 JSON 序列化再调用rfc5424.encode(SYSLOG, INFO, ctx.var.host, apisix, ctx.var.pid, json_str)生成标准 Syslog 报文见 syslog/init.lua 与 rfc5424.lua批量入队报文首先尝试加入已存在的批处理器缓冲add_entry不存在则创建新处理器add_entry_to_new_processor达到batch_max_size或inactive_timeout触发回调socket 发送回调中通过logger_socket:new创建连接参数含 host/port/flush_limit/drop_limit/timeout/sock_type/pool_size/tls并以 LRU 缓存TTL 300 秒复用 logger 对象最后调用logger:log发送见 syslog/init.lua失败时按max_retry_count与retry_delay重试手动冲刷插件导出flush_syslog供需要时手动调用logger:flush立即刷出缓冲数据测试用例 t/plugin/syslog.t 演示了手动 flush 的用法。此外批处理器管理器会以 30 分钟为周期清理已空的缓冲对象避免内存中残留过期处理器见 batch-processor-manager.lua。总结syslog 插件为 APISIX 网关提供了标准、可靠的 Syslog 日志输出通道它既能以原生 RFC 5424 协议对接传统 Syslog 服务又能携带完整 JSON 化的访问日志上下文配合批量处理器在高并发场景下保持发送效率通过log_format路由级或插件元数据级可灵活裁剪日志字段include_req_body/include_resp_body则满足请求/响应体级别的审计需求。结合 syslog 插件源码、底层实现 与 测试用例开发者可以快速将其集成到自己的日志采集链路中。【免费下载链接】apisixThe Cloud-Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/ap/apisix创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
延伸阅读

更多相关文章

2026/9/15 18:23:24

Automatisch 集成 Twitter:OAuth 1.0a 连接配置完全指南

Automatisch 集成 Twitter:OAuth 1.0a 连接配置完全指南 【免费下载链接】automatisch The open source Zapier alternative. Build workflow automation without spending time and money. 项目地址: https://gitcode.com/GitHub_Trending/au/automatisch 本…

2026/9/15 18:38:25

中文字体子集化:精准裁剪而非压缩的工程实践

1. 为什么中文字体子集化不是“压缩”而是“外科手术式裁剪”很多人第一次听说“中文字体子集化”,下意识就联想到 ZIP 压缩、图片 WebP 转换——这是最典型的认知偏差。我去年给一个面向海外用户的中文内容平台做性能优化时,也犯过这个错:直…

2026/9/15 18:38:25

ZZULIOJ刷题全攻略:从入门基础到算法进阶的题解整合与避坑指南

我记得第一次在新生群里看到“ZZULIOJ”这五个字母时,整个人是懵的。页面白底黑字,左侧一排深色菜单,点进去是一道道看着都认识的题,但提交后不是“编译错误”就是“答案错误”。后来我在这套OJ上从大一刷到大四,从被s…

2026/9/15 18:38:25

北京学会网站建设避坑指南:小白不踩雷实操手册

北京学会网站建设避坑指南:小白不踩雷实操手册 想在北京做个像样的网站,心里没底?自己不会代码,又怕被坑?别慌。 这三年我在北京海淀、朝阳跑遍了各大软件园,见过太多初创团队花大价钱做了个“四不像”网站,最后因为服务器卡顿、SEO做废、备案拖延…

2026/9/15 4:54:30

拯救者Y7000黑屏故障排查与维修实战指南

1. 项目概述:一台黑屏的拯救者Y7000,到底卡在哪一步? 联想拯救者Y7000系列笔记本,从2018年第一代搭载i5-8300H开始,到后来的i7-9750H、i7-10750H、i5-11400H,再到2023年款的R7-7840HS,它始终是学…

2026/9/15 0:01:16

AI英语单词APP开发:自适应学习算法与移动端优化实践

1. 项目概述 作为一名在移动应用开发领域摸爬滚打多年的老手,我最近完成了一个AI英语单词APP的开发项目。这个项目将传统单词记忆方法与现代AI技术相结合,打造了一款能够智能适应不同用户学习习惯的英语学习工具。 市面上大多数单词APP都存在一个通病&a…

2026/9/15 0:01:16

Flutter与OpenHarmony结合开发手语学习APP实战

1. 项目背景与核心价值作为一名同时接触过Flutter和OpenHarmony的开发者,最近我完成了一个基于Flutter for OpenHarmony的手语学习APP实战项目。这个项目最大的特点在于实现了跨平台框架与国产操作系统深度结合的创新实践——用Flutter开发的应用能完美运行在OpenHa…

2026/9/15 0:01:16

六个月成为机器人工程师:从ROS2到SLAM的实战路径

1. 六个月的紧迫感从哪来:先搞清楚你要成为哪种机器人工程师说实话,六个月的期限并不是一个宽松的时间线。市面上任何一本正经的机器人学教材都超过五百页,ROS2的官方文档可以翻到你怀疑人生,再加上ABB、KUKA这些工业机器人厂家动…

2026/9/15 14:22:53

USB Type-C PCB布局分区设计:电源、高速信号与PD协议全攻略

做硬件这行,Type-C接口算是典型的“看着简单,做起来全坑”的东西。光引脚就24个,高低速信号、电源、控制线全部塞在一个小小的连接器里,如果PCB布局不做规划,打样回来基本就是“插上没反应”、“高速掉线”、“静电一打…

2026/9/14 13:53:59

系统编程学习原型如何补齐稳定性边界

系统编程学习原型如何补齐稳定性边界预算有限时&#xff0c;我先优化明显多余的复制&#xff0c;而不是猜测性地换容器。用借用传递只读数据通常就能减少分配&#xff1a; fn parse(line: &str) -> Result<Item, Error> { /* ... */ }用基准确认热点确实在分配&am…

2026/9/15 11:42:23

雨花区哪家财务公司代理记账比较好?

在雨花区&#xff0c;企业处理财税事务常常面临诸多挑战&#xff0c;选择一家靠谱的财务公司至关重要。湖南巨勤财务管理咨询有限公司就是本地正规实体财税服务机构&#xff0c;深耕本地工商财税行业多年&#xff0c;熟悉当地工商局、税务局最新政策与申报流程。主营公司注册、…

还想了解更多?直接咨询顾问

免费诊断 + 免费方案 + 透明报价。

全国咨询热线400-8866-253
免费获取方案
咨询二维码