a7-plugin-skywalking

Overview

The skywalking plugin integrates API7 EE 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 (Gateway Group)

In API7 EE, global settings like the SkyWalking endpoint are typically configured at the gateway group level.

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

Step-by-Step: Enable SkyWalking Tracing

1. Ensure SkyWalking OAP is reachable

Verify your SkyWalking OAP server is running and accessible from the API7 EE gateway nodes.

2. Configure gateway group settings

Configure the skywalking plugin attributes in your API7 EE gateway group.

3. Enable on a service-backed route

Replace <gateway-group-id> with the ID returned by a7 gateway-group list -o json, then enable tracing:

a7 service create --gateway-group <gateway-group-id> -f - <<'EOF'
{
  "id": "traced-api-service",
  "name": "Traced API service",
  "upstream": {
    "type": "roundrobin",
    "nodes": [{"host": "backend", "port": 8080, "weight": 1}]
  }
}
EOF

a7 route create --gateway-group <gateway-group-id> -f - <<'EOF'
{
  "id": "traced-api",
  "name": "Traced API route",
  "paths": ["/api/*"],
  "service_id": "traced-api-service",
  "plugins": {
    "skywalking": {
      "sample_ratio": 1
    }
  }
}
EOF

4. Send a request and view traces

curl http://localhost:9080/api/hello

View traces in SkyWalking UI at the configured address.

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.

Enable globally via Global Rule

Do not set an id in the create payload. The CLI derives the Global Rule ID from the plugin name.

a7 global-rule create --gateway-group <gateway-group-id> -f - <<'EOF'
{
  "plugins": {
    "skywalking": {
      "sample_ratio": 0.5
    }
  }
}
EOF

Span Structure

The plugin creates two spans per request:

• entrySpan: From request arrival to response completion
• exitSpan: From upstream call start to response received

Troubleshooting

Symptom	Cause	Fix
No traces in SkyWalking UI	Wrong endpoint_addr	Verify OAP is reachable from gateway nodes
Missing service in topology	service_name mismatch	Check service name in gateway group config
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
Config not applied	Wrong gateway group specified	Ensure --gateway-group matches the desired cluster

Config Sync Example

Save the following as skywalking.yaml:

version: "1"
services:
  - id: traced-api-service
    name: Traced API service
    upstream:
      type: roundrobin
      nodes:
        - host: backend
          port: 8080
          weight: 1
routes:
  - id: traced-api
    name: Traced API route
    paths:
      - /api/*
    service_id: traced-api-service
    plugins:
      skywalking:
        sample_ratio: 1

Validate and apply this partial configuration to the target gateway group:

a7 config validate -f skywalking.yaml
a7 config sync -g <gateway-group-id> -f skywalking.yaml --delete=false

Disabling deletion preserves resources that are not included in this partial configuration.

---

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