a6-plugin-skywalking

Overview

The skywalking plugin integrates APISIX with Apache SkyWalking for distributed tracing. It creates entry and exit spans for each request, reports them to SkyWalking OAP via HTTP, and enables service topology visualization and performance analysis.

When to Use

• Trace requests across microservices via SkyWalking
• Visualize service topology and dependency maps
• Analyze per-route and per-service latency
• Correlate traces with logs using skywalking-logger

Plugin Configuration Reference (Route/Service)

Field	Type	Required	Default	Description
sample_ratio	number	No	1	Sampling rate from 0.00001 to 1 (1 = trace all)

Global Configuration (config.yaml)

Configure in APISIX config.yaml under plugin_attr:

Field	Type	Default	Description
service_name	string	"APISIX"	Service name in SkyWalking UI
service_instance_name	string	"APISIX Instance Name"	Instance name (use $hostname for dynamic)
endpoint_addr	string	http://127.0.0.1:12800	SkyWalking OAP HTTP endpoint
report_interval	integer	3	Reporting interval in seconds

plugin_attr:
  skywalking:
    service_name: api-gateway
    service_instance_name: "$hostname"
    endpoint_addr: http://skywalking-oap:12800
    report_interval: 5

Step-by-Step: Enable SkyWalking Tracing

1. Ensure SkyWalking OAP is running

# Docker example
docker run -d --name skywalking-oap \
  -p 12800:12800 -p 11800:11800 \
  apache/skywalking-oap-server:latest

2. Configure APISIX global settings

Add to config.yaml:

plugin_attr:
  skywalking:
    service_name: my-gateway
    service_instance_name: "$hostname"
    endpoint_addr: http://skywalking-oap:12800

3. Enable on a route

a6 route create -f - <<'EOF'
{
  "id": "traced-api",
  "uri": "/api/*",
  "plugins": {
    "skywalking": {
      "sample_ratio": 1
    }
  },
  "upstream": {
    "type": "roundrobin",
    "nodes": {
      "backend:8080": 1
    }
  }
}
EOF

4. Send a request and view traces

curl http://127.0.0.1:9080/api/hello

View traces in SkyWalking UI at http://skywalking-ui:8080.

Common Patterns

Partial sampling (production)

{
  "plugins": {
    "skywalking": {
      "sample_ratio": 0.1
    }
  }
}

Traces 10% of requests. Sufficient for production traffic analysis without excessive overhead.

Trace-log correlation with skywalking-logger

{
  "plugins": {
    "skywalking": {
      "sample_ratio": 1
    },
    "skywalking-logger": {
      "endpoint_addr": "http://skywalking-oap:12800"
    }
  }
}

Associates access logs with trace IDs in the SkyWalking UI, enabling click-through from traces to logs.

Enable globally

curl "$(a6 context current -o json | jq -r .server)/apisix/admin/global_rules" \
  -X PUT \
  -H "X-API-KEY: $(a6 context current -o json | jq -r .api_key)" \
  -d '{
    "id": "skywalking-global",
    "plugins": {
      "skywalking": {
        "sample_ratio": 0.5
      }
    }
  }'

Span Structure

The plugin creates two spans per request:

• entrySpan: From request arrival to response completion (component ID 6002)
• exitSpan: From upstream call start to response received (component ID 6002)

Config Sync Example

version: "1"
routes:
  - id: traced-api
    uri: /api/*
    plugins:
      skywalking:
        sample_ratio: 1
    upstream_id: my-upstream
upstreams:
  - id: my-upstream
    type: roundrobin
    nodes:
      "backend:8080": 1

Troubleshooting

Symptom	Cause	Fix
No traces in SkyWalking UI	Wrong endpoint_addr	Verify OAP is reachable at the configured address
Missing service in topology	service_name mismatch	Check plugin_attr.skywalking.service_name in config.yaml
High overhead	sample_ratio: 1 in production	Lower to 0.01-0.1 for high-traffic routes
Traces not correlated	Backend not instrumented	Install SkyWalking agent in upstream services
Plugin not working	Not in plugins list	Ensure skywalking is in the plugins array in config.yaml

---

This page is generated from a6-plugin-skywalking/SKILL.md in the api7/a6 repository. Browse all skills on the AI Agent Skills page.