This plugin is compatible with DB-less mode.

In DB-less mode, you configure Kong Gateway . Therefore, the Admin API is mostly read-only. The only tasks it can perform are all related to handling the declarative config, including:

  • Setting a target’s health status in the load balancer
  • Validating configurations against schemas
  • Uploading the declarative configuration using the endpoint

Admin API

Kubernetes

Declarative (YAML)

Kong Manager

For example, configure this plugin on a service by making the following request:

SERVICE is the id or name of the service that this plugin configuration will target.

First, create a resource:

  1. apiVersion: configuration.konghq.com/v1
  2. kind: KongPlugin
  3. metadata:
  4. name: <zipkin-example>
  5. config:
  6. local_service_name: kong
  7. http_endpoint: http://your.zipkin.collector:9411/api/v2/spans
  8. sample_ratio: 0.001
  9. include_credential: true
  10. traceid_byte_count: 16
  11. header_type: preserve
  12. default_header_type: b3
  13. tags_header: Zipkin-Tags
  14. plugin: zipkin

Next, apply the KongPlugin resource to a Service by annotating the Service as follows:

  1. apiVersion: v1
  2. kind: Service
  3. metadata:
  4. name: {SERVICE}
  5. labels:
  6. app: {SERVICE}
  7. annotations:
  8. konghq.com/plugins: <zipkin-example>
  9. spec:
  10. ports:
  11. - port: 80
  12. targetPort: 80
  13. protocol: TCP
  14. name: {SERVICE}
  15. selector:
  16. app: {SERVICE}

{SERVICE} is the id or name of the service that this plugin configuration will target.

Note: The KongPlugin resource only needs to be defined once and can be applied to any service, consumer, or route in the namespace. If you want the plugin to be available cluster-wide, create the resource as a KongClusterPlugin instead of KongPlugin.

For example, configure this plugin on a by adding this section to your declarative configuration file:

  1. plugins:
  2. - name: zipkin
  3. service: {SERVICE}
  4. config:
  5. local_service_name: kong
  6. http_endpoint: http://your.zipkin.collector:9411/api/v2/spans
  7. sample_ratio: 0.001
  8. include_credential: true
  9. traceid_byte_count: 16
  10. header_type: preserve
  11. default_header_type: b3
  12. tags_header: Zipkin-Tags

SERVICE is the id or name of the service that this plugin configuration will target.

Configure this plugin on a service:

  1. In Kong Manager, select the workspace.
  2. From the Dashboard, scroll down to Services and click View for the service row.
  3. Scroll down to plugins and click Add Plugin.
  4. Find and select the Zipkin plugin.

    Note: If the plugin is greyed out, then it is not available for your product tier. See Kong Gateway tiers.

  5. If the option is available, select Scoped.

  6. Add the service name and ID to the Service field if it is not already prefilled.
  7. Enter the following , updating the default or sample values as needed:

    • Config.Local Service Name: kong
    • Config.Include Credential: select checkbox
    • Config.Traceid Byte Count: 16
    • Config.Header Type: preserve
    • Config.Default Header Type: b3
    • Config.Tags Header: Zipkin-Tags
  8. Click Create.

Enable the plugin on a route

Admin API

Kubernetes

Declarative (YAML)

Kong Manager

For example, configure this plugin on a with:

  1. $ curl -X POST http://{HOST}:8001/routes/{ROUTE}/plugins \
  2. --data "name=zipkin" \
  3. --data "config.local_service_name=kong" \
  4. --data "config.http_endpoint=http://your.zipkin.collector:9411/api/v2/spans" \
  5. --data "config.sample_ratio=0.001" \
  6. --data "config.include_credential=true" \
  7. --data "config.traceid_byte_count=16" \
  8. --data "config.header_type=preserve" \
  9. --data "config.default_header_type=b3" \
  10. --data "config.tags_header=Zipkin-Tags"

ROUTE is the id or name of the route that this plugin configuration will target.

First, create a KongPlugin resource:

Then, apply it to an ingress () by annotating the ingress as follows:

  1. apiVersion: networking/v1beta1
  2. kind: Ingress
  3. metadata:
  4. name: {ROUTE}
  5. annotations:
  6. kubernetes.io/ingress.class: kong
  7. spec:
  8. rules:
  9. - host: examplehostname.com
  10. http:
  11. paths:
  12. - path: /bar
  13. backend:
  14. serviceName: echo
  15. servicePort: 80

ROUTE is the id or name of the route that this plugin configuration will target.

Note: The KongPlugin resource only needs to be defined once and can be applied to any service, consumer, or route in the namespace. If you want the plugin to be available cluster-wide, create the resource as a KongClusterPlugin instead of KongPlugin.

For example, configure this plugin on a route by adding this section to your declarative configuration file:

  1. plugins:
  2. - name: zipkin
  3. route: <route>
  4. config:
  5. local_service_name: kong
  6. http_endpoint: http://your.zipkin.collector:9411/api/v2/spans
  7. sample_ratio: 0.001
  8. include_credential: true
  9. traceid_byte_count: 16
  10. header_type: preserve
  11. default_header_type: b3
  12. tags_header: Zipkin-Tags

ROUTE is the id or name of the route that this plugin configuration will target.

Configure this plugin on a route:

  1. In Kong Manager, select the workspace.
  2. From the Dashboard, select Routes in the left navigation.
  3. Click View for the route row.
  4. Scroll down to plugins and click Add Plugin.
  5. Note: If the plugin is greyed out, then it is not available for your product tier. See .

  6. If the option is available, select Scoped.

  7. Add the Route ID if it is not already prefilled.
  8. Enter the following parameters, updating the default or sample values as needed:

    • Config.Local Service Name: kong
    • Config.Include Credential: select checkbox
    • Config.Traceid Byte Count: 16
    • Config.Header Type:
    • Config.Default Header Type: b3
    • Config.Tags Header: Zipkin-Tags
  9. Click Create.

Enabling the plugin on a consumer

Admin API

Kubernetes

Declarative (YAML)

Kong Manager

For example, configure this plugin on a consumer with:

  1. $ curl -X POST http://{HOST}:8001/consumers/{CONSUMER}/plugins \
  2. --data "name=zipkin" \
  3. --data "config.local_service_name=kong" \
  4. --data "config.http_endpoint=http://your.zipkin.collector:9411/api/v2/spans" \
  5. --data "config.sample_ratio=0.001" \
  6. --data "config.include_credential=true" \
  7. --data "config.traceid_byte_count=16" \
  8. --data "config.header_type=preserve" \
  9. --data "config.default_header_type=b3" \
  10. --data "config.tags_header=Zipkin-Tags"

CONSUMER is the id or username of the consumer that this plugin configuration will target.

You can combine consumer.id, service.id, or route.id in the same request, to further narrow the scope of the plugin.

First, create a resource:

  1. apiVersion: configuration.konghq.com/v1
  2. kind: KongPlugin
  3. metadata:
  4. name: <zipkin-example>
  5. config:
  6. local_service_name: kong
  7. http_endpoint: http://your.zipkin.collector:9411/api/v2/spans
  8. sample_ratio: 0.001
  9. include_credential: true
  10. traceid_byte_count: 16
  11. header_type: preserve
  12. default_header_type: b3
  13. tags_header: Zipkin-Tags
  14. plugin: zipkin

Then, apply it to a consumer by annotating the KongConsumer resource as follows:

CONSUMER is the id or username of the consumer that this plugin configuration will target.

Note: The KongPlugin resource only needs to be defined once and can be applied to any Service, Consumer, or Route in the namespace. If you want the plugin to be available cluster-wide, create the resource as a KongClusterPlugin instead of KongPlugin.

For example, configure this plugin on a by adding this section to your declarative configuration file:

  1. plugins:
  2. - name: zipkin
  3. consumer: {CONSUMER}
  4. config:
  5. local_service_name: kong
  6. http_endpoint: http://your.zipkin.collector:9411/api/v2/spans
  7. sample_ratio: 0.001
  8. include_credential: true
  9. traceid_byte_count: 16
  10. header_type: preserve
  11. default_header_type: b3
  12. tags_header: Zipkin-Tags

CONSUMER is the id or username of the consumer that this plugin configuration will target.

Configure this plugin on a consumer:

  1. In Kong Manager, select the workspace.
  2. From the Dashboard, scroll down to Consumers and click View for the consumer row.
  3. Select the Plugins tab.
  4. Click Add Plugin.
  5. Find and select the Zipkin plugin.

    Note: If the plugin is greyed out, then it is not available for your product tier. See Kong Gateway tiers.

  6. If the option is available, select Global.

  7. Enter the following , updating the default or sample values as needed:

    • Config.Local Service Name: kong
    • Config.Include Credential: select checkbox
    • Config.Traceid Byte Count: 16
    • Config.Header Type: preserve
    • Config.Default Header Type: b3
    • Config.Tags Header: Zipkin-Tags
  8. Click Create.

A plugin which is not associated to any service, route, or consumer is considered global, and will be run on every request. Read the Plugin Reference and the sections for more information.

Admin API

Kubernetes

Declarative (YAML)

Kong Manager

For example, configure this plugin globally with:

  1. --data "name=zipkin" \
  2. --data "config.local_service_name=kong" \
  3. --data "config.http_endpoint=http://your.zipkin.collector:9411/api/v2/spans" \
  4. --data "config.sample_ratio=0.001" \
  5. --data "config.include_credential=true" \
  6. --data "config.traceid_byte_count=16" \
  7. --data "config.header_type=preserve" \
  8. --data "config.default_header_type=b3" \
  9. --data "config.tags_header=Zipkin-Tags"

Create a KongClusterPlugin resource and label it as global:

  1. apiVersion: configuration.konghq.com/v1
  2. kind: KongClusterPlugin
  3. metadata:
  4. name: <global-zipkin>
  5. annotations:
  6. kubernetes.io/ingress.class: kong
  7. labels:
  8. global: \"true\"
  9. config:
  10. local_service_name: kong
  11. http_endpoint: http://your.zipkin.collector:9411/api/v2/spans
  12. sample_ratio: 0.001
  13. include_credential: true
  14. traceid_byte_count: 16
  15. header_type: preserve
  16. default_header_type: b3
  17. tags_header: Zipkin-Tags
  18. plugin: zipkin

For example, configure this plugin using the plugins: entry in the declarative configuration file:

  1. plugins:
  2. - name: zipkin
  3. config:
  4. local_service_name: kong
  5. http_endpoint: http://your.zipkin.collector:9411/api/v2/spans
  6. sample_ratio: 0.001
  7. include_credential: true
  8. traceid_byte_count: 16
  9. header_type: preserve
  10. default_header_type: b3
  11. tags_header: Zipkin-Tags

Configure this plugin globally:

  1. In Kong Manager, select the workspace.
  2. From the Dashboard, select Plugins in the left navigation.
  3. Click New Plugin.
  4. Find and select the Zipkin plugin.

    Note: If the plugin is greyed out, then it is not available for your product tier. See .

  5. Enter the following parameters, updating the default/sample values as needed:

    • Config.Local Service Name: kong
    • Config.Include Credential: select checkbox
    • Config.Traceid Byte Count: 16
    • Config.Header Type: preserve
    • Config.Default Header Type: b3
    • Config.Tags Header: Zipkin-Tags
  6. Click Create.

Parameters

Here’s a list of all the parameters which can be used in this plugin’s configuration:

When enabled, this plugin traces requests in a way compatible with .

The code is structured around an opentracing core using the to collect timing data of a request in each of Kong’s phases. The plugin uses opentracing-lua compatible extractor, injector, and reporters to implement Zipkin’s protocols.

Reporter

An opentracing “reporter” is how tracing data is reported to another system. This plugin records tracing data for a given request, and sends it as a batch to a Zipkin server using . Note that zipkin version 1.31 or higher is required.

The http_endpoint configuration variable must contain the full uri including scheme, host, port and path sections (i.e. your uri likely ends in /api/v2/spans).

The plugin does request sampling. For each request which triggers the plugin, a random number between 0 and 1 is chosen.

If the number is greater than the configured sample_ratio, then a trace with several spans will be generated. If sample_ratio is set to 1, then all requests will generate a trace (this might be very noisy).

For each request that gets traced, the following spans are produced:

  • Request span: 1 per request. Encompasses the whole request in kong (kind: SERVER). The Proxy and Balancer spans are children of this span. It contains the following logs/annotations for the rewrite phase:

    • krs - kong.rewrite.start
    • krf - kong.rewrite.finish

    The Request span has the following tags:

    • lc: Hardcoded to kong.
    • kong.service: The uuid of the service matched when processing the request, if any.
    • kong.service_name: The name of the service matched when processing the request, if service exists and has a name attribute.
    • kong.route: The uuid of the route matched when processing the request, if any (it can be nil on non-matched requests).
    • kong.route_name: The name of the route matched when processing the request, if route exists and has a name attribute.
    • http.method: The HTTP method used on the original request (only for HTTP requests).
    • http.path: The path of the request (only for HTTP requests).
    • If the plugin tags_header config option is set, and the request contains headers with the appropriate name and correct encoding tags, then the trace will include the tags.
    • If the plugin static_tags config option is set, then the tags in the config option will be included in the trace.
  • Proxy span: 1 per request, encompassing most of Kong’s internal processing of a request (kind: CLIENT). Contains the following logs/annotations for the start/finish of the of the Kong plugin phases:
    • kas - kong.access.start
    • kaf - kong.access.finish
    • kbs - kong.body_filter.start
    • kbf - kong.body_filter.finish
    • khs - kong.header_filter.start
    • khf - kong.header_filter.finish
    • kps - kong.preread.start (only for stream requests)
    • kpf - kong.preread.finish (only for stream requests)
  • Balancer span(s): 0 or more per request, each encompassing one balancer attempt (kind: CLIENT). Contains the following tags specific to load balancing:
    • kong.balancer.try: A number indicating the attempt (1 for the first load-balancing attempt, 2 for the second, and so on).
    • peer.ipv4 or peer.ipv6 for the balancer IP.
    • peer.port for the balanced port.
    • error: Set to true if the balancing attempt was unsuccessful, otherwise unset.
    • http.status_code: The HTTP status code received, in case of error.
    • kong.balancer.state: An NGINX-specific description of the error, next/failed for HTTP failures, or 0 for stream failures. Equivalent to state_name in OpenResty’s balancer’s get_last_failure function.

See also


1.5.x

  • Added a new option for the header_type parameter