SkyWalking
The skywalking plugin supports integration with Apache SkyWalking for request tracing.
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.
Example
To follow along the example, start a SkyWalking storage, OAP server, and Booster UI:
- Docker
- Kubernetes
Start a storage, OAP and Booster UI with Docker Compose, following SkyWalking's documentation. Once set up, the OAP server should be listening on 12800 and you should be able to access the UI at http://localhost:8080.
Deploy SkyWalking OAP server and UI to your Kubernetes cluster following SkyWalking's documentation. For a quick start, you can use the SkyWalking Helm chart.
Once deployed, the OAP server is typically accessible at skywalking-oap.skywalking.svc.cluster.local:12800 within the cluster.
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.
- Host or Docker
- Kubernetes (Helm)
For APISIX host or Docker deployments, keep the existing plugin list in config.yaml, add skywalking, and update plugin_attr.skywalking:
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://192.168.2.103:12800
Reload the gateway for configuration changes to take effect.
For Helm deployments, update the values that render the SkyWalking plugin attributes. For APISIX, also update the value that renders the gateway plugin list. Keep the rest of your values file unchanged.
For the APISIX Helm chart, apisix.plugins replaces the loaded plugin list. Start from the complete plugin list used by your gateway, add skywalking, and configure the plugin attributes under apisix.pluginAttrs:
apisix:
plugins:
# Keep the complete plugin list used by your gateway.
- skywalking
pluginAttrs:
skywalking:
report_interval: 3
service_name: APISIX
service_instance_name: APISIX Instance
endpoint_addr: http://192.168.2.103:12800
For the API7 Gateway Helm chart, set the following values:
pluginAttrs:
skywalking:
report_interval: 3
service_name: APISIX
service_instance_name: APISIX Instance
endpoint_addr: http://192.168.2.103:12800
Then apply the values file with the chart used for this gateway release:
helm upgrade <release-name> <chart-name> -n <namespace> -f values.yaml
Trace All Requests
The following example demonstrates how you can trace all requests passing through a route.
Create a route with skywalking and configure the sampling ratio to be 1 to trace all requests:
- Admin API
- ADC
- Ingress Controller
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"
}
}'
services:
- name: httpbin
routes:
- uris:
- /anything
name: skywalking-route
plugins:
skywalking:
sample_ratio: 1
upstream:
type: roundrobin
nodes:
- host: httpbin.org
port: 80
weight: 1
Synchronize the configuration to the gateway:
adc sync -f adc.yaml
- Gateway API
- APISIX CRD
apiVersion: v1
kind: Service
metadata:
namespace: aic
name: httpbin-external-domain
spec:
type: ExternalName
externalName: httpbin.org
---
apiVersion: apisix.apache.org/v1alpha1
kind: PluginConfig
metadata:
namespace: aic
name: skywalking-plugin-config
spec:
plugins:
- name: skywalking
config:
sample_ratio: 1
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
namespace: aic
name: skywalking-route
spec:
parentRefs:
- name: apisix
rules:
- matches:
- path:
type: Exact
value: /anything
filters:
- type: ExtensionRef
extensionRef:
group: apisix.apache.org
kind: PluginConfig
name: skywalking-plugin-config
backendRefs:
- name: httpbin-external-domain
port: 80
apiVersion: apisix.apache.org/v2
kind: ApisixUpstream
metadata:
namespace: aic
name: httpbin-external-domain
spec:
ingressClassName: apisix
externalNodes:
- type: Domain
name: httpbin.org
---
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
namespace: aic
name: skywalking-route
spec:
ingressClassName: apisix
http:
- name: skywalking-route
match:
paths:
- /anything
upstreams:
- name: httpbin-external-domain
plugins:
- name: skywalking
enable: true
config:
sample_ratio: 1
Apply the configuration to your cluster:
kubectl apply -f skywalking-ic.yaml
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 SkyWalking UI, navigate to General Service > Services. You should see a service called APISIX with traces corresponding to your requests:
Associate Traces with Logs
The following example demonstrates how you can configure the skywalking-logger plugin on a route to log information of requests hitting the route.
Create a route with the skywalking-logger plugin and configure the plugin with your OAP server URI:
- Admin API
- ADC
- Ingress Controller
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://192.168.2.103:12800"
}
},
"upstream": {
"nodes": {
"httpbin.org:80": 1
},
"type": "roundrobin"
}
}'
services:
- name: httpbin
routes:
- uris:
- /anything
name: skywalking-logger-route
plugins:
skywalking:
sample_ratio: 1
skywalking-logger:
endpoint_addr: "http://192.168.2.103:12800"
upstream:
type: roundrobin
nodes:
- host: httpbin.org
port: 80
weight: 1
Synchronize the configuration to the gateway:
adc sync -f adc.yaml
- Gateway API
- APISIX CRD
apiVersion: v1
kind: Service
metadata:
namespace: aic
name: httpbin-external-domain
spec:
type: ExternalName
externalName: httpbin.org
---
apiVersion: apisix.apache.org/v1alpha1
kind: PluginConfig
metadata:
namespace: aic
name: skywalking-logs-config
spec:
plugins:
- name: skywalking
config:
sample_ratio: 1
- name: skywalking-logger
config:
endpoint_addr: "http://skywalking-oap.skywalking.svc.cluster.local:12800"
---
apiVersion: gateway.networking.k8s.io/v1
kind: HTTPRoute
metadata:
namespace: aic
name: skywalking-route
spec:
parentRefs:
- name: apisix
rules:
- matches:
- path:
type: Exact
value: /anything
filters:
- type: ExtensionRef
extensionRef:
group: apisix.apache.org
kind: PluginConfig
name: skywalking-logs-config
backendRefs:
- name: httpbin-external-domain
port: 80
apiVersion: apisix.apache.org/v2
kind: ApisixUpstream
metadata:
namespace: aic
name: httpbin-external-domain
spec:
ingressClassName: apisix
externalNodes:
- type: Domain
name: httpbin.org
---
apiVersion: apisix.apache.org/v2
kind: ApisixRoute
metadata:
namespace: aic
name: skywalking-route
spec:
ingressClassName: apisix
http:
- name: skywalking-route
match:
paths:
- /anything
upstreams:
- name: httpbin-external-domain
plugins:
- name: skywalking
enable: true
config:
sample_ratio: 1
- name: skywalking-logger
enable: true
config:
endpoint_addr: "http://skywalking-oap.skywalking.svc.cluster.local:12800"
Apply the configuration to your cluster:
kubectl apply -f skywalking-logs-ic.yaml
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 SkyWalking UI, navigate to General Service > Services. You should see a service called APISIX with a trace corresponding to your request, where you can view the associated logs:
