/kong-plugin-zipkin

A Kong plugin for propogating zipkin spans and reporting spans to a zipkin server

Primary LanguageLuaApache License 2.0Apache-2.0

Build Status

Getting Started

Get a running Zipkin instance

e.g. using docker:

sudo docker run -d -p 9411:9411 openzipkin/zipkin

Enable the Plugin

curl --url http://localhost:8001/plugins/ -d name=zipkin -d config.http_endpoint=http://127.0.0.1:9411/api/v2/spans

See many more details of using this plugin at https://docs.konghq.com/plugins/zipkin/

Implementation

The Zipkin plugin is derived from an OpenTracing base.

A tracer is created with the "http_headers" formatter set to use the headers described in b3-propagation

Spans

  • Request span: 1 per request. Encompasses the whole request in kong (kind: SERVER). The proxy span and balancer spans are children of this span. Contains logs/annotations for the kong.rewrite phase start and end
  • Proxy span: 1 per request. Encompassing most of Kong's internal processing of a request (kind: CLIENT) Contains logs/annotations for the rest start/finish of the of the Kong plugin phases:
    • krs - kong.rewrite.start
    • krf - kong.rewrite.finish
    • 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
    • kpf - kong.preread.finish This kind of information is useful for finding performance problems in plugins.
  • Balancer span(s): 0 or more per request, each encompassing one balancer attempt (kind: CLIENT) Contains tags specific to the load balancing:
    • kong.balancer.try: a number indicating the attempt order
    • peer.ipv4/peer.ipv6 + peer.port for the balanced port
    • error: true/false depending on whether the balancing could be done or not
    • 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, 0 for stream failures. Equivalent to state_name in OpenResty's Balancer's get_last_failure function.

Tags

Standard tags

"Standard" tags are documented here Of those, this plugin currently uses:

  • span.kind (sent to Zipkin as "kind")
  • http.method
  • http.status_code
  • http.path
  • error
  • peer.ipv4
  • peer.ipv6
  • peer.port
  • peer.hostname
  • peer.service

Non-Standard tags

In addition to the above standardised tags, this plugin also adds:

  • component (sent to Zipkin as "lc", for "local component")
  • kong.api (deprecated)
  • kong.consumer
  • kong.credential
  • kong.node.id
  • kong.route
  • kong.service
  • kong.balancer.try
  • kong.balancer.state

Logs / Annotations

Logs (annotations in Zipkin) are used to encode the begin and end of every kong phase.

  • kong.rewrite, start / finish, <timestamp>
  • kong.access, start / finish, <timestamp>
  • kong.preread, start / finish, <timestamp>
  • kong.header_filter, start / finish, <timestamp>
  • kong.body_filter, start / finish, <timestamp>

They are transmitted to Zipkin as annotations where the value is the concatenation of the log name and the value.

For example, the kong.rewrite, start log would be transmitted as:

  • { "value" = "kong.rewrite.start", timestamp = <timestamp> }