跳到主要内容

skywalking-logger

skywalking-logger 插件将请求和响应日志作为 JSON 对象分批发送到 SkyWalking OAP 服务器。你可以自定义每条日志中包含的字段。

如果存在追踪上下文，插件会依据 SkyWalking 跨进程传播请求头协议自动建立追踪与日志之间的关联。

示例​

以下示例展示如何将请求日志发送到 SkyWalking、自定义日志内容，以及将日志与分布式追踪关联。

创建 SkyWalking 容器使用的网络：

docker network create gateway-skywalking-net

如果网关也在 Docker 中运行，请设置 GATEWAY_CONTAINER 并将其连接到该网络。如果网关安装在主机上，请跳过此步骤：

export GATEWAY_CONTAINER=replace-with-gateway-container-name
docker network connect gateway-skywalking-net "$GATEWAY_CONTAINER"

创建以下 Docker Compose 文件：

skywalking-compose.yaml
services:
  banyandb:
    image: apache/skywalking-banyandb:0.11.0
    command: standalone
    networks:
      - skywalking

  oap:
    image: apache/skywalking-oap-server:11.0.0
    environment:
      SW_STORAGE: banyandb
      SW_STORAGE_BANYANDB_TARGETS: banyandb:17912
    ports:
      - "127.0.0.1:12800:12800"
    depends_on:
      - banyandb
    networks:
      skywalking:
        aliases:
          - skywalking-oap

  horizon:
    image: apache/skywalking-ui:horizon-1.0.0
    environment:
      HORIZON_OAP_QUERY_URL: http://skywalking-oap:12800
      HORIZON_OAP_ADMIN_URL: http://skywalking-oap:17128
      HORIZON_AUTH_LOCAL_USERS: '[{"username":"admin","passwordHash":"$$argon2id$$v=19$$m=65536,t=3,p=4$$eemqy1r72oSXR58y8VpRqw$$Bn/dULrmJTHEi3263KfgWDEwQmUsqNLi3xwyv/DekHM","roles":["admin"]}]'
    ports:
      - "127.0.0.1:8081:8081"
    depends_on:
      - oap
    networks:
      - skywalking

networks:
  skywalking:
    name: gateway-skywalking-net
    external: true

启动服务：

docker compose -f skywalking-compose.yaml up -d

Horizon 可通过 http://localhost:8081 访问。使用用户名 admin 和密码 admin 登录。

警告

本示例中的本地用户使用公开的演示凭证。请仅在可信的本地评估环境中使用这些凭证。将 Horizon 暴露到本地环境之外前，请配置身份提供商或生成唯一的密码哈希。

下文 Admin API 和 ADC 示例使用 Docker 网络中的地址 http://skywalking-oap:12800。对于安装在主机上的网关，请改用 http://127.0.0.1:12800。如果网关通过 Kubernetes 访问 OAP，请使用 http://skywalking-oap.skywalking.svc.cluster.local:12800。Ingress Controller 示例已使用 Kubernetes Service 地址。

使用默认日志格式记录请求​

以下示例将某一路由的请求日志发送到 SkyWalking。

创建启用 skywalking-logger 插件的路由，并使用 OAP 服务器 URI 配置该插件：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "skywalking-logger-route",
    "uri": "/anything",
    "plugins": {
      "skywalking-logger": {
        "endpoint_addr": "http://skywalking-oap:12800"
      }
    },
    "upstream": {
      "nodes": {
        "httpbin.org:80": 1
      },
      "type": "roundrobin"
    }
  }'

向路由发送请求：

curl -i "http://127.0.0.1:9080/anything"

你应收到 HTTP/1.1 200 OK 响应。

在 Horizon 中，前往 General Service → Logs，选择 APISIX 服务并运行查询。你应看到与该请求对应的日志条目。地址、时间值和版本信息会因环境而异：

{
  "upstream_latency": 3407,
  "request": {
    "method": "GET",
    "headers": {
      "user-agent": "curl/8.7.1",
      "host": "127.0.0.1:9080",
      "accept": "*/*"
    },
    "url": "http://127.0.0.1:9080/anything",
    "size": 107,
    "querystring": {},
    "uri": "/anything"
  },
  "client_ip": "192.168.155.1",
  "route_id": "skywalking-logger-route",
  "start_time": 1789693705560,
  "upstream": "34.195.250.0:80",
  "server": {
    "version": "3.18.0",
    "hostname": "dd2886d0b7bf"
  },
  "service_id": "",
  "response": {
    "size": 881,
    "status": 200,
    "headers": {
      "content-type": "application/json",
      "date": "Fri, 18 Sep 2026 01:08:29 GMT",
      "server": "APISIX/3.18.0",
      "access-control-allow-origin": "*",
      "connection": "close",
      "access-control-allow-credentials": "true",
      "content-length": "653"
    }
  },
  "latency": 6791.0001277924,
  "apisix_latency": 3384.0001277924
}

使用插件元数据记录请求头和响应头​

以下示例使用插件元数据，为每个 skywalking-logger 实例添加选定的请求头和响应头。元数据值引用内置变量，因此一份配置可在多个路由和服务中应用相同的日志字段。

首先，创建启用 skywalking-logger 插件的路由，并使用 OAP 服务器 URI 配置该插件，配置方式与使用默认日志格式记录请求相同。

接下来，为 skywalking-logger 配置插件元数据：

curl "http://127.0.0.1:9180/apisix/admin/plugin_metadata/skywalking-logger" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "log_format": {
      "host": "$host",
      "@timestamp": "$time_iso8601",
      "client_ip": "$remote_addr",
      "env": "$http_env",
      "resp_content_type": "$sent_http_Content_Type"
    }
  }'

❶ 记录自定义请求头 env。

❷ 记录响应头 Content-Type。

携带 env 请求头向路由发送请求：

curl -i "http://127.0.0.1:9080/anything" -H "env: dev"

你应收到 HTTP/1.1 200 OK 响应。在 Horizon 中，前往 General Service → Logs，选择 APISIX 服务并运行查询。日志条目应包含已配置的字段：

[
  {
    "route_id": "skywalking-logger-route",
    "client_ip": "192.168.65.1",
    "@timestamp": "2026-09-18T01:08:29+00:00",
    "host": "127.0.0.1",
    "env": "dev",
    "resp_content_type": "application/json"
  }
]

有条件地记录请求体​

以下示例仅在请求符合配置条件时记录请求体。

创建启用 skywalking-logger 插件的路由：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "skywalking-logger-route",
    "uri": "/anything",
    "plugins": {
      "skywalking-logger": {
        "endpoint_addr": "http://skywalking-oap:12800",
        "include_req_body": true,
        "include_req_body_expr": [["arg_log_body", "==", "yes"]]
      }
    },
    "upstream": {
      "nodes": {
        "httpbin.org:80": 1
      },
      "type": "roundrobin"
    }
  }'

❶ include_req_body：设置为 true 时记录请求体。

❷ include_req_body_expr：仅当 URL 查询参数 log_body 等于 yes 时记录请求体。

使用符合条件的 URL 查询参数向路由发送请求：

curl -i "http://127.0.0.1:9080/anything?log_body=yes" -X POST -d '{"env": "dev"}'

你应收到 HTTP/1.1 200 OK 响应。在 Horizon 中，前往 General Service → Logs，选择 APISIX 服务并运行查询。日志条目应包含请求体：

[
  {
    "request": {
      "url": "http://127.0.0.1:9080/anything?log_body=yes",
      "querystring": {
        "log_body": "yes"
      },
      "uri": "/anything?log_body=yes",
      ...,
      "body": "{\"env\": \"dev\"}",
    },
    ...
  }
]

不带任何 URL 查询参数向路由发送请求：

curl -i "http://127.0.0.1:9080/anything" -X POST -d '{"env": "dev"}'

你不应看到不包含请求体的日志条目。

信息

自定义日志格式不会自动添加已采集的请求体或响应体。请在格式中包含相应变量：

{
  "include_req_body": true,
  "include_resp_body": true,
  "log_format": {
    "request_body": "$request_body",
    "response_body": "$resp_body"
  }
}

请求体和响应体大小限制仍然适用。使用 log_format_extra 可在不替换默认日志条目的情况下添加自定义字段。

将追踪与日志关联​

以下示例在同一路由上启用追踪和请求日志记录，使 Horizon 能够将每条日志与其追踪关联。

SkyWalking 设置

本示例还要求全局启用 skywalking 插件，并为其配置可访问的 OAP 端点地址。对于 Helm 部署，请参阅 SkyWalking 插件设置。

创建启用 skywalking-logger 插件的路由，并使用 OAP 服务器 URI 配置该插件：

curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -d '{
    "id": "skywalking-logger-route",
    "uri": "/anything",
    "plugins": {
      "skywalking": {
        "sample_ratio": 1
      },
      "skywalking-logger": {
        "endpoint_addr": "http://skywalking-oap:12800"
      }
    },
    "upstream": {
      "nodes": {
        "httpbin.org:80": 1
      },
      "type": "roundrobin"
    }
  }'

向路由发送几次请求：

curl -i "http://127.0.0.1:9080/anything"

你应收到 HTTP/1.1 200 OK 响应。

在 Horizon 中，前往 General Service → Logs 并运行查询。关联的请求日志包含一个 trace 链接，单击该链接可打开对应的追踪：

Horizon 显示与追踪关联的 APISIX 请求日志