ARTICLE DETAIL

资讯详情

深耕网站建设、视觉设计与SEO优化的一线实战洞察。

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

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),仅供参考
返回列表