Apache APISIX skywalking-logger 插件接入 SkyWalking OAP 的访问日志上报实战指南【免费下载链接】apisixThe Cloud-Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/ap/apisix导读skywalking-logger是 Apache APISIX 提供的一款日志类插件用于将网关产生的访问日志以 JSON 格式批量推送到 SkyWalking OAP Server通过 HTTP 协议实现网关层访问日志的集中采集、检索与观测。若请求链路中已存在 SkyWalking 的追踪上下文sw8请求头插件会自动完成 trace-log 关联让日志与调用链无缝打通。阅读本文后你将掌握该插件的全部配置参数、日志格式定制方法、启用与删除流程以及底层批处理器与上报协议的实现原理。插件功能概述skywalking-logger的定位非常清晰把 APISIX 作为 SkyWalking 生态中的日志数据源。它会在每个请求的日志阶段log阶段采集请求/响应元数据组装成 SkyWalking OAP Server 要求的日志上报结构再经由批量处理器聚合后通过POST /v3/logs接口提交到 OAP Server。插件源码位于 apisix/plugins/skywalking-logger.lua其核心特性可以归纳为三点HTTP 上报直接通过 HTTP 调用 OAP Server 的/v3/logs日志上报接口无需额外部署 AgentTrace-Log 自动关联当请求携带 SkyWalking 跨进程传播协议头sw8时自动解析其中的 traceId、traceSegmentId、spanId 并写入日志条目批量聚合发送依托 APISIX 的 Batch Processor 机制将大量日志合并为少量 HTTP 请求避免高频提交对 OAP Server 造成压力。Attributes 配置项详解插件的全部配置属性定义在源码 schema 段 中与官方文档保持严格一致名称类型必填默认值取值范围说明endpoint_addrstring是--SkyWalking OAP Server 的 URI 地址例如http://127.0.0.1:12800service_namestring否APISIX-上报到 SkyWalking 的服务名service_instance_namestring否APISIX Instance Name-服务实例名设为$hostname时自动取本机主机名log_formatobject否--自定义日志格式键值对形式值仅支持字符串以$开头的值会解析为 APISIX 变量或 Nginx 变量timeoutinteger否3[1,...]连接 OAP Server 的超时时间秒namestring否skywalking logger-日志器唯一标识使用 Prometheus 监控 APISIX 指标时该名称会以apisix_batch_process_entries指标标签形式导出include_req_bodyboolean否false[false, true]是否在日志中包含请求体include_req_body_exprarray否--配合include_req_body使用只有当该表达式lua-resty-expr 语法求值为true时才记录请求体include_resp_bodyboolean否false[false, true]是否在日志中包含响应体include_resp_body_exprarray否--配合include_resp_body使用按表达式条件过滤响应体采集从源码看endpoint_addr被定义为core.schema.uri_def且位于required列表因此在配置校验时是强制的——测试用例 t/plugin/skywalking-logger.t 中的 TEST 3 正是验证了缺失endpoint_addr时返回property endpoint_addr is required错误。关键参数解读service_instance_name 与$hostname源码 L159-L162 显示当配置值为字面量$hostname时会通过core.utils.gethostname()替换为实际主机名便于在 K8s 等多实例部署下区分日志来源实例log_format 的变量注入以$开头的值会被 log-util 识别为变量名见 log-util.lua L72-L83并从ctx.var中取值可同时使用 APISIX 变量与 Nginx 变量批量处理器参数由于插件 schema 经过batch_processor_manager:wrap_schema(schema)包装见 skywalking-logger.lua L76你还可以额外配置 Batch Processor 的专属属性如batch_max_size、max_retry_count、retry_delay、buffer_duration、inactive_timeout等定义见 batch-processor.lua L37-L47。默认日志格式与上报结构当未配置自定义log_format时插件会使用 APISIX 的完整访问日志结构。上报到 OAP Server 的顶层结构如下{ serviceInstance: APISIX Instance Name, body: { json: { json: body-json } }, endpoint: /opentracing, service: APISIX }其中body.json.json字段是经过转义的 JSON 字符串即完整的访问日志内容。展开后大致如下{ response: { status: 200, headers: { server: APISIX/3.7.0, content-type: text/plain, transfer-encoding: chunked, connection: close }, size: 136 }, route_id: 1, upstream: 127.0.0.1:1982, upstream_latency: 8, apisix_latency: 101.00020599365, client_ip: 127.0.0.1, service_id: , server: { hostname: localhost, version: 3.7.0 }, start_time: 1704429712768, latency: 109.00020599365, request: { headers: { content-length: 9, host: localhost, connection: close }, method: POST, body: body-data, size: 94, querystring: {}, url: http://localhost:1984/opentracing, uri: /opentracing } }这份完整日志由 log-util.lua 的 get_full_log 函数 生成包含请求信息方法、URL、URI、请求头、查询串、请求大小、响应信息状态码、响应头、字节数、服务端信息主机名、APISIX 版本、路由/服务 ID、上游地址、客户端 IP以及latency总时延、upstream_latency上游时延、apisix_latencyAPISIX 自身处理时延单位均为毫秒等关键性能字段。sw8 追踪上下文关联插件在log阶段读取请求头sw8SkyWalking Cross Process Propagation Headers Protocol v3 格式形如1-TRACEID-SEGMENTID-SPANID-PARENT_SERVICE-PARENT_INSTANCE-PARENT_ENDPOINT-IPPORT并按-拆分解析见 skywalking-logger.lua L144-L157若拆分为8 段则提取traceId、traceSegmentId、spanId其中 ID 为 Base64URL 编码需解码并写入上报条目的traceContext字段若格式不合法如只有 7 段会记录警告日志failed to parse trace_context header但不会中断日志上报。测试用例 TEST 6 / TEST 7 分别验证了正确与错误 sw8 头两种场景正确时日志中出现traceContext中的三个字段错误时仅输出解析失败的警告。Metadata全局自定义日志格式除插件级log_format外还可以通过 Plugin Metadata 配置全局日志格式名称类型必填默认值说明log_formatobject否-全局日志格式键值对形式值仅支持字符串支持$前缀变量重要Plugin Metadata 的作用域是全局的配置后会影响所有使用了skywalking-logger插件的 Route 与 Service。若插件自身也配置了log_format则以插件级配置优先见 log-util.lua L269-L271。配置全局格式前先从conf/config.yaml中取出 admin keyadmin_key$(yq .deployment.admin.admin_key[0].key conf/config.yaml | sed s///g)然后通过 Admin API 写入curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/skywalking-logger -H X-API-KEY: $admin_key -X PUT -d { log_format: { host: $host, timestamp: $time_iso8601, client_ip: $remote_addr } }配置生效后上报的日志将按自定义字段输出例如{host:localhost,timestamp:2020-09-23T19:05:05-04:00,client_ip:127.0.0.1,route_id:1} {host:localhost,timestamp:2020-09-23T19:05:05-04:00,client_ip:127.0.0.1,route_id:1}值得注意当使用自定义格式时日志中会自动附带route_id与service_id字段见 log-util.lua L97-L102方便在 SkyWalking 中按路由维度过滤分析。测试用例 TEST 8 / TEST 9 对该流程做了端到端验证。启用插件在 SkyWalking OAP Server 部署就绪后即可将插件绑定到指定 Routecurl http://127.0.0.1:9180/apisix/admin/routes/1 -H X-API-KEY: $admin_key -X PUT -d { plugins: { skywalking-logger: { endpoint_addr: http://127.0.0.1:12800 } }, upstream: { type: roundrobin, nodes: { 127.0.0.1:1980: 1 } }, uri: /hello }随后请求网关即可在 OAP Server 中看到对应日志curl -i http://127.0.0.1:9080/hello更完整的启用示例采集请求/响应体若需要把请求体与响应体一并采集可参考以下配置对应测试 TEST 13 / TEST 14 的用法curl http://127.0.0.1:9180/apisix/admin/routes/1 -H X-API-KEY: $admin_key -X PUT -d { plugins: { skywalking-logger: { endpoint_addr: http://127.0.0.1:12800, include_req_body: true, include_resp_body: true } }, upstream: { type: roundrobin, nodes: { 127.0.0.1:1980: 1 } }, uri: /hello }采集到的请求体会出现在日志的request.body字段响应体出现在response.body字段。从 log-util.lua L33-L34 可以看到请求体与响应体的采集上限均为 512 KiBMAX_REQ_BODY/MAX_RESP_BODY超出部分会被截断避免大体积 body 拖垮日志管道。底层上报流程批量处理器与 /v3/logs理解底层机制有助于排查上报延迟或丢失问题。整个链路如下日志采集log阶段调用log_util.get_log_entry生成日志条目默认走get_full_log完整格式自定义时走get_custom_format_log入队调用batch_processor_manager:add_entry将条目加入批量队列批量触发默认每5 秒或队列累积到1000 条时触发一次批量提交buffer_duration与batch_max_size可调组装上报条目被编码为 JSON 数组通过send_http_data函数发送。send_http_data见 skywalking-logger.lua L91-L133的实现要点解析endpoint_addr得到 host 与 port使用resty.http建立连接超时时间取自timeout配置秒乘以 1000 转为毫秒向/v3/logs路径发送POST请求Content-Type为application/json若 OAP 返回状态码 ≥ 400则视为失败并返回错误信息交由批量处理器按重试策略处理。批处理器的重试机制见 batch-processor.lua L80-L113支持max_retry_count次重试默认 0 次重试间隔由retry_delay控制超过重试上限后丢弃批次并记录错误日志。调试时可在 APISIX error.log 中观察到Batch Processor[skywalking logger] successfully processed the entries之类的日志对应测试 TEST 5 的断言。删除插件移除插件只需将 Route 配置中的plugins置空即可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 } } }若此前配置过全局 Metadata 且希望一并清理可删除对应的plugin_metadata资源。常见问题与排查建议日志未出现在 OAP Server优先检查endpoint_addr是否正确指向 OAP Server 的 HTTP 端口默认 12800并确认上报路径为/v3/logs同时观察 error.log 中是否有failed to connect to host或server returned status code错误见 skywalking-logger.lua L104-L130想降低上报频率调大buffer_duration默认 60 秒插件文档示例按 5 秒描述与batch_max_size默认 1000减少 HTTP 请求次数日志字段太多想精简通过插件级log_format或 Metadata 级log_format自定义输出字段仅保留$host、$time_iso8601、$remote_addr等关键变量需要按条件采集请求体使用include_req_body_expr结合 lua-resty-expr 表达式做精细化过滤降低存储成本监控上报情况配合 Prometheus 插件name字段会以apisix_batch_process_entries指标导出可用于观测批量处理队列的积压与丢弃情况。总结skywalking-logger让 APISIX 网关日志与 SkyWalking 观测平台无缝对接它复用 SkyWalking 标准的 HTTP 日志上报协议/v3/logs自动解析sw8传播头完成 trace-log 关联并借助 Batch Processor 以可控的频率批量提交日志。通过插件级与 Metadata 级log_format的双重定制能力以及请求体/响应体按需采集功能你可以灵活控制日志的字段粒度、采集范围与上报节奏将其作为 SkyWalking 可观测性体系中稳定、低开销的网关日志数据源。关键参考文件插件源码apisix/plugins/skywalking-logger.lua日志工具库apisix/utils/log-util.lua批量处理器apisix/utils/batch-processor.lua端到端测试t/plugin/skywalking-logger.t官方文档docs/en/latest/plugins/skywalking-logger.md【免费下载链接】apisixThe Cloud-Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/ap/apisix创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/9/15 4:53:06 · 阅读 1.2k Apache APISIX skywalking-logger 插件：接入 SkyWalking OAP 的访问日志上报实战指南
Apache APISIX skywalking-logger 插件接入 SkyWalking OAP 的访问日志上报实战指南【免费下载链接】apisixThe Cloud-Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/ap/apisix导读skywalking-logger是 Apache APISIX 提供的一款日志类插件用于将网关产生的访问日志以 JSON 格式批量推送到 SkyWalking OAP Server通过 HTTP 协议实现网关层访问日志的集中采集、检索与观测。若请求链路中已存在 SkyWalking 的追踪上下文sw8请求头插件会自动完成 trace-log 关联让日志与调用链无缝打通。阅读本文后你将掌握该插件的全部配置参数、日志格式定制方法、启用与删除流程以及底层批处理器与上报协议的实现原理。插件功能概述skywalking-logger的定位非常清晰把 APISIX 作为 SkyWalking 生态中的日志数据源。它会在每个请求的日志阶段log阶段采集请求/响应元数据组装成 SkyWalking OAP Server 要求的日志上报结构再经由批量处理器聚合后通过POST /v3/logs接口提交到 OAP Server。插件源码位于 apisix/plugins/skywalking-logger.lua其核心特性可以归纳为三点HTTP 上报直接通过 HTTP 调用 OAP Server 的/v3/logs日志上报接口无需额外部署 AgentTrace-Log 自动关联当请求携带 SkyWalking 跨进程传播协议头sw8时自动解析其中的 traceId、traceSegmentId、spanId 并写入日志条目批量聚合发送依托 APISIX 的 Batch Processor 机制将大量日志合并为少量 HTTP 请求避免高频提交对 OAP Server 造成压力。Attributes 配置项详解插件的全部配置属性定义在源码 schema 段 中与官方文档保持严格一致名称类型必填默认值取值范围说明endpoint_addrstring是--SkyWalking OAP Server 的 URI 地址例如http://127.0.0.1:12800service_namestring否APISIX-上报到 SkyWalking 的服务名service_instance_namestring否APISIX Instance Name-服务实例名设为$hostname时自动取本机主机名log_formatobject否--自定义日志格式键值对形式值仅支持字符串以$开头的值会解析为 APISIX 变量或 Nginx 变量timeoutinteger否3[1,...]连接 OAP Server 的超时时间秒namestring否skywalking logger-日志器唯一标识使用 Prometheus 监控 APISIX 指标时该名称会以apisix_batch_process_entries指标标签形式导出include_req_bodyboolean否false[false, true]是否在日志中包含请求体include_req_body_exprarray否--配合include_req_body使用只有当该表达式lua-resty-expr 语法求值为true时才记录请求体include_resp_bodyboolean否false[false, true]是否在日志中包含响应体include_resp_body_exprarray否--配合include_resp_body使用按表达式条件过滤响应体采集从源码看endpoint_addr被定义为core.schema.uri_def且位于required列表因此在配置校验时是强制的——测试用例 t/plugin/skywalking-logger.t 中的 TEST 3 正是验证了缺失endpoint_addr时返回property endpoint_addr is required错误。关键参数解读service_instance_name 与$hostname源码 L159-L162 显示当配置值为字面量$hostname时会通过core.utils.gethostname()替换为实际主机名便于在 K8s 等多实例部署下区分日志来源实例log_format 的变量注入以$开头的值会被 log-util 识别为变量名见 log-util.lua L72-L83并从ctx.var中取值可同时使用 APISIX 变量与 Nginx 变量批量处理器参数由于插件 schema 经过batch_processor_manager:wrap_schema(schema)包装见 skywalking-logger.lua L76你还可以额外配置 Batch Processor 的专属属性如batch_max_size、max_retry_count、retry_delay、buffer_duration、inactive_timeout等定义见 batch-processor.lua L37-L47。默认日志格式与上报结构当未配置自定义log_format时插件会使用 APISIX 的完整访问日志结构。上报到 OAP Server 的顶层结构如下{ serviceInstance: APISIX Instance Name, body: { json: { json: body-json } }, endpoint: /opentracing, service: APISIX }其中body.json.json字段是经过转义的 JSON 字符串即完整的访问日志内容。展开后大致如下{ response: { status: 200, headers: { server: APISIX/3.7.0, content-type: text/plain, transfer-encoding: chunked, connection: close }, size: 136 }, route_id: 1, upstream: 127.0.0.1:1982, upstream_latency: 8, apisix_latency: 101.00020599365, client_ip: 127.0.0.1, service_id: , server: { hostname: localhost, version: 3.7.0 }, start_time: 1704429712768, latency: 109.00020599365, request: { headers: { content-length: 9, host: localhost, connection: close }, method: POST, body: body-data, size: 94, querystring: {}, url: http://localhost:1984/opentracing, uri: /opentracing } }这份完整日志由 log-util.lua 的 get_full_log 函数 生成包含请求信息方法、URL、URI、请求头、查询串、请求大小、响应信息状态码、响应头、字节数、服务端信息主机名、APISIX 版本、路由/服务 ID、上游地址、客户端 IP以及latency总时延、upstream_latency上游时延、apisix_latencyAPISIX 自身处理时延单位均为毫秒等关键性能字段。sw8 追踪上下文关联插件在log阶段读取请求头sw8SkyWalking Cross Process Propagation Headers Protocol v3 格式形如1-TRACEID-SEGMENTID-SPANID-PARENT_SERVICE-PARENT_INSTANCE-PARENT_ENDPOINT-IPPORT并按-拆分解析见 skywalking-logger.lua L144-L157若拆分为8 段则提取traceId、traceSegmentId、spanId其中 ID 为 Base64URL 编码需解码并写入上报条目的traceContext字段若格式不合法如只有 7 段会记录警告日志failed to parse trace_context header但不会中断日志上报。测试用例 TEST 6 / TEST 7 分别验证了正确与错误 sw8 头两种场景正确时日志中出现traceContext中的三个字段错误时仅输出解析失败的警告。Metadata全局自定义日志格式除插件级log_format外还可以通过 Plugin Metadata 配置全局日志格式名称类型必填默认值说明log_formatobject否-全局日志格式键值对形式值仅支持字符串支持$前缀变量重要Plugin Metadata 的作用域是全局的配置后会影响所有使用了skywalking-logger插件的 Route 与 Service。若插件自身也配置了log_format则以插件级配置优先见 log-util.lua L269-L271。配置全局格式前先从conf/config.yaml中取出 admin keyadmin_key$(yq .deployment.admin.admin_key[0].key conf/config.yaml | sed s///g)然后通过 Admin API 写入curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/skywalking-logger -H X-API-KEY: $admin_key -X PUT -d { log_format: { host: $host, timestamp: $time_iso8601, client_ip: $remote_addr } }配置生效后上报的日志将按自定义字段输出例如{host:localhost,timestamp:2020-09-23T19:05:05-04:00,client_ip:127.0.0.1,route_id:1} {host:localhost,timestamp:2020-09-23T19:05:05-04:00,client_ip:127.0.0.1,route_id:1}值得注意当使用自定义格式时日志中会自动附带route_id与service_id字段见 log-util.lua L97-L102方便在 SkyWalking 中按路由维度过滤分析。测试用例 TEST 8 / TEST 9 对该流程做了端到端验证。启用插件在 SkyWalking OAP Server 部署就绪后即可将插件绑定到指定 Routecurl http://127.0.0.1:9180/apisix/admin/routes/1 -H X-API-KEY: $admin_key -X PUT -d { plugins: { skywalking-logger: { endpoint_addr: http://127.0.0.1:12800 } }, upstream: { type: roundrobin, nodes: { 127.0.0.1:1980: 1 } }, uri: /hello }随后请求网关即可在 OAP Server 中看到对应日志curl -i http://127.0.0.1:9080/hello更完整的启用示例采集请求/响应体若需要把请求体与响应体一并采集可参考以下配置对应测试 TEST 13 / TEST 14 的用法curl http://127.0.0.1:9180/apisix/admin/routes/1 -H X-API-KEY: $admin_key -X PUT -d { plugins: { skywalking-logger: { endpoint_addr: http://127.0.0.1:12800, include_req_body: true, include_resp_body: true } }, upstream: { type: roundrobin, nodes: { 127.0.0.1:1980: 1 } }, uri: /hello }采集到的请求体会出现在日志的request.body字段响应体出现在response.body字段。从 log-util.lua L33-L34 可以看到请求体与响应体的采集上限均为 512 KiBMAX_REQ_BODY/MAX_RESP_BODY超出部分会被截断避免大体积 body 拖垮日志管道。底层上报流程批量处理器与 /v3/logs理解底层机制有助于排查上报延迟或丢失问题。整个链路如下日志采集log阶段调用log_util.get_log_entry生成日志条目默认走get_full_log完整格式自定义时走get_custom_format_log入队调用batch_processor_manager:add_entry将条目加入批量队列批量触发默认每5 秒或队列累积到1000 条时触发一次批量提交buffer_duration与batch_max_size可调组装上报条目被编码为 JSON 数组通过send_http_data函数发送。send_http_data见 skywalking-logger.lua L91-L133的实现要点解析endpoint_addr得到 host 与 port使用resty.http建立连接超时时间取自timeout配置秒乘以 1000 转为毫秒向/v3/logs路径发送POST请求Content-Type为application/json若 OAP 返回状态码 ≥ 400则视为失败并返回错误信息交由批量处理器按重试策略处理。批处理器的重试机制见 batch-processor.lua L80-L113支持max_retry_count次重试默认 0 次重试间隔由retry_delay控制超过重试上限后丢弃批次并记录错误日志。调试时可在 APISIX error.log 中观察到Batch Processor[skywalking logger] successfully processed the entries之类的日志对应测试 TEST 5 的断言。删除插件移除插件只需将 Route 配置中的plugins置空即可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 } } }若此前配置过全局 Metadata 且希望一并清理可删除对应的plugin_metadata资源。常见问题与排查建议日志未出现在 OAP Server优先检查endpoint_addr是否正确指向 OAP Server 的 HTTP 端口默认 12800并确认上报路径为/v3/logs同时观察 error.log 中是否有failed to connect to host或server returned status code错误见 skywalking-logger.lua L104-L130想降低上报频率调大buffer_duration默认 60 秒插件文档示例按 5 秒描述与batch_max_size默认 1000减少 HTTP 请求次数日志字段太多想精简通过插件级log_format或 Metadata 级log_format自定义输出字段仅保留$host、$time_iso8601、$remote_addr等关键变量需要按条件采集请求体使用include_req_body_expr结合 lua-resty-expr 表达式做精细化过滤降低存储成本监控上报情况配合 Prometheus 插件name字段会以apisix_batch_process_entries指标导出可用于观测批量处理队列的积压与丢弃情况。总结skywalking-logger让 APISIX 网关日志与 SkyWalking 观测平台无缝对接它复用 SkyWalking 标准的 HTTP 日志上报协议/v3/logs自动解析sw8传播头完成 trace-log 关联并借助 Batch Processor 以可控的频率批量提交日志。通过插件级与 Metadata 级log_format的双重定制能力以及请求体/响应体按需采集功能你可以灵活控制日志的字段粒度、采集范围与上报节奏将其作为 SkyWalking 可观测性体系中稳定、低开销的网关日志数据源。关键参考文件插件源码apisix/plugins/skywalking-logger.lua日志工具库apisix/utils/log-util.lua批量处理器apisix/utils/batch-processor.lua端到端测试t/plugin/skywalking-logger.t官方文档docs/en/latest/plugins/skywalking-logger.md【免费下载链接】apisixThe Cloud-Native API Gateway项目地址: https://gitcode.com/GitHub_Trending/ap/apisix创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考