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. APISIX supports HTTP protocol to interact with the SkyWalking server.

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.

Update APISIX configuration file to enable the skywalking plugin, which is disabled by default, and update the endpoint address:

config.yaml
plugins:
  - skywalking
  - ...

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

Reload APISIX for configuration changes to take effect.

Ingress Controller

If you are using the Ingress Controller with Helm, update the plugin list and SkyWalking plugin attributes in the Helm values file and run helm upgrade. For more information, see the Helm chart values reference.

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"
    }
  }'

adc.yaml
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

skywalking-ic.yaml
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

skywalking-ic.yaml
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:

SkyWalking APISIX traces

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"
    }
  }'

adc.yaml
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

skywalking-logs-ic.yaml
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

skywalking-logs-ic.yaml
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:

trace context

associated log

Example​

Trace All Requests​

Associate Traces with Logs​

Example

Trace All Requests

Associate Traces with Logs