StatsD

The StatsD plugin logs metrics for a Gateway Service or Route to a StatsD server. It can also be used to log metrics on the Collectd daemon by enabling its StatsD plugin.

By default, the plugin sends a packet for each metric it observes. The config.udp_packet_size option configures the greatest datagram size the plugin can combine. It should be less than 65507, according to UDP protocol. Consider the MTU of the network when setting this parameter.

The following configure the metrics that will be logged:

If a request URI doesn’t match any Routes, the following metrics are sent instead:

If you enable the tag_style configuration for the StatsD plugin, the following metrics are sent instead:

The StatsD Plugin supports Librato, InfluxDB, DogStatsD, and SignalFX-style tags, which are used like Prometheus labels.

• Librato-style tags: Must be appended to the metric name with a delimiting #, for example: metric.name#tagName=val,tag2Name=val2:0|c See the Librato StatsD documentation for more information.

• InfluxDB-style tags: Must be appended to the metric name with a delimiting comma, for example: metric.name,tagName=val,tag2Name=val2:0|c See the InfluxDB StatsD documentation for more information.

• DogStatsD-style tags: Appended as a |# delimited section at the end of the metric, for example: metric.name:0|c|#tagName:val,tag2Name:val2 See the Datadog StatsD Tags documentation for more information about the concept description and Datagram Format. AWS CloudWatch also uses the DogStatsD protocol.

• SignalFX dimension: Add the tags to the metric name in square brackets, for example: metric.name[tagName=val,tag2Name=val2]:0|c See the SignalFX StatsD documentation for more information.

When config.tag_style is enabled, Kong Gateway uses a filter label, like service, route, workspace, consumer, node, or status, on the metrics tags to see if these can be found. For shdict_usage metrics, only node and shdict are added.

For example:

kong.request.size,workspace=default,route=d02485d7-8a28-4ec2-bc0b-caabed82b499,status=200,consumer=d24d866a-020a-4605-bc3c-124f8e1d5e3f,service=bdabce05-e936-4673-8651-29d2e9eca382,node=c80a9c5845bd:120|c

Metric fields

The StatsD plugin can be configured with any combination of metrics, with each entry containing the following fields:

Metric behavior

• All metrics are logged by default.
• Metrics with a stat_type of counter or gauge require the sample_rate field.
• The unique_users metric only supports the set stat type.
• The following metrics only support the counter stat type:
  • status_count
  • status_count_per_user
  • status_count_per_user_per_route
  • request_per_user
• The shdict_usage metric only supports the gauge stat type.
• The following metrics require a consumer_identifier:
  • status_count_per_user
  • request_per_user
  • unique_users
  • status_count_per_user_per_route
• The service_identifier field is optional for all metrics. If not set, it defaults to service_name_or_host.
• The status_count_per_workspace metric requires a workspace_identifier.

This logging plugin logs HTTP request and response data, and also supports stream data (TCP, TLS, and UDP). The Kong Gateway process error file is the Nginx error file. You can find it at the following path: {prefix}/logs/error.log

The StatsD plugin uses internal queues to decouple the production of log entries from their transmission to the upstream log server.

With queuing, request information is put in a configurable queue before being sent in batches to the upstream server. This has the following benefits:

• Reduces any possible concurrency on the upstream server
• Helps deal with temporary outages of the upstream server due to network or administrative changes
• Can reduce resource usage both in Kong Gateway and on the upstream server by collecting multiple entries from the queue in one request

Note: Because queues are structural elements for components in Kong Gateway, they only live in the main memory of each worker process and are not shared between workers. Therefore, queued content isn’t preserved under abnormal operational situations, like power loss or unexpected worker process shutdown due to memory shortage or program errors.

You can configure several parameters for queuing:

When a Kong Gateway shutdown is initiated, the queue is flushed. This allows Kong Gateway to shut down even if it was waiting for new entries to be batched, ensuring upstream servers can be contacted.

Queues are not shared between workers and queuing parameters are scoped to one worker. For whole-system capacity planning, the number of workers needs to be considered when setting queue parameters.