Docs
Plugin HubOverview

SkyWalking

The skywalking plugin sends distributed traces from APISIX and API7 Gateway to Apache SkyWalking.

SkyWalking uses its native NGINX Lua tracer to provide tracing, topology analysis, and metrics from both service and URI perspectives. The gateway communicates with the SkyWalking server over HTTP.

Tracing adds work to each sampled request. Use sample_ratio to balance trace coverage against that overhead, and use a lower ratio on high-throughput routes when full sampling is unnecessary. Requests that are not selected for sampling skip trace creation, but the performance effect depends on the workload and collector configuration.

Examples

The examples use SkyWalking OAP 11.0.0 with BanyanDB 0.11.0 and Horizon 1.0.0. Start the SkyWalking services in the same environment as the gateway:

Create the network used by the SkyWalking containers:

docker network create gateway-skywalking-net

If the gateway also runs in Docker, set GATEWAY_CONTAINER and connect it to the network. Skip this step for a host-installed gateway:

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

Create the following Docker Compose file:

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

Start the services:

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

Horizon is available at http://localhost:8081. Sign in with username admin and password admin.

caution

The local user in this example uses public demonstration credentials. Use it only for a trusted local evaluation. Configure an identity provider or generate a unique password hash before exposing Horizon outside the local environment.

For a host-installed gateway, use http://127.0.0.1:12800.

After the SkyWalking OAP server is available, configure the gateway according to how it was deployed. In API7 Gateway, skywalking is available in Dashboard and Admin API by default. For APISIX deployments, load skywalking in the gateway plugin list before setting the endpoint address for the SkyWalking OAP server.

For an APISIX host deployment, keep the existing plugin list in config.yaml, add skywalking, and set plugin_attr.skywalking.endpoint_addr to the OAP port published on the host:

config.yaml
plugins:
  # Keep the complete plugin list used by your gateway.
  - skywalking

plugin_attr:
  skywalking:
    report_interval: 3
    service_name: APISIX
    service_instance_name: APISIX Instance
    endpoint_addr: http://127.0.0.1:12800

Reload the gateway for configuration changes to take effect.

Trace All Requests

The following example traces every request passing through a route.

Create a route with skywalking and configure the sampling ratio to be 1 to trace all requests:

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

Send a few requests to the route:

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

You should receive HTTP/1.1 200 OK responses.

In Horizon, navigate to General Service → Traces and run a query. You should see traces for the APISIX service:

Horizon showing traces created by requests through APISIX

Associate Traces with Logs

The following example sends request logs from a traced route to SkyWalking, allowing Horizon to link each log entry to its trace.

Create a route with the skywalking-logger plugin and configure the plugin with your OAP server 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"
    }
  }'

Generate a few requests to the route:

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

You should receive HTTP/1.1 200 OK responses.

In Horizon, navigate to General Service → Logs and run a query. The correlated request log includes a trace link that opens its trace:

Horizon showing APISIX request logs linked to their traces

Configuration Options

Next Page