StatsD Advanced plugin

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

The StatsD Advanced plugin provides features not available in the open-source StatsD plugin, such as:

Ability to choose status codes to log to metrics.
More granular status codes per workspace.
Ability to use TCP instead of UDP.

Configuration Reference

This plugin is compatible with DB-less mode.

In DB-less mode, you configure Kong Gateway declaratively. 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 /config endpoint

Example plugin configuration

Enable on a service

Enable on a route

Enable on a consumer

Enable globally

The following examples provide some typical configurations for enabling the statsd-advanced plugin on a service.

Admin API

Kubernetes

Declarative (YAML)

Konnect Cloud

Kong Manager

Make the following request:

curl -X POST http://{HOST}:8001/services/{SERVICE}/plugins \
    --data "name=statsd-advanced"  \
    --data "config.host=127.0.0.1" \
    --data "config.port=8125" \
    --data "config.metrics=All metrics are logged" \
    --data "config.prefix=kong" \
    --data "config.hostname_in_prefix=false" \
    --data "config.udp_packet_size=0 (not combined)" \
    --data "config.use_tcp=false" \
    --data "config.allow_status_codes=200-205" \
    --data "config.allow_status_codes=400-499"

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

First, create a KongPlugin resource:

apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: <statsd-advanced-example>
config: 
  host: 127.0.0.1
  port: 8125
  metrics: All metrics are logged
  prefix: kong
  hostname_in_prefix: false
  udp_packet_size: 0 (not combined)
  use_tcp: false
  allow_status_codes:
  - 200-205
  - 400-499
plugin: statsd-advanced

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

apiVersion: v1
kind: Service
metadata:
  name: {SERVICE}
  labels:
    app: {SERVICE}
  annotations:
    konghq.com/plugins: <statsd-advanced-example>
spec:
  ports:
  - port: 80
    targetPort: 80
    protocol: TCP
    name: {SERVICE}
  selector:
    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.

Add this section to your declarative configuration file:

plugins:
- name: statsd-advanced
  service: {SERVICE}
  config: 
    host: 127.0.0.1
    port: 8125
    metrics: All metrics are logged
    prefix: kong
    hostname_in_prefix: false
    udp_packet_size: 0 (not combined)
    use_tcp: false
    allow_status_codes:
    - 200-205
    - 400-499

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

In Konnect Cloud, select the service on the ServiceHub page.
Scroll down to Versions and select the version.
Scroll down to Plugins and click New Plugin.
Find and select the StatsD Advanced plugin.
Enter the following parameters, updating the default or sample values as needed:
- Config.Host: 127.0.0.1
- Config.Port: 8125
- Config.Metrics: All metrics are logged
- Config.Prefix: kong
- Config.Hostname In Prefix: clear checkbox
- Config.Udp Packet Size: ``0 (not combined)
- Config.Use Tcp: clear checkbox
- Config.Allow Status Codes: 200-205
- Config.Allow Status Codes: 400-499
Click Create.

In Kong Manager, select the workspace.
From the Dashboard, scroll down to Services and click View for the service row.
Scroll down to plugins and click Add Plugin.
Find and select the StatsD Advanced plugin.

Note: If the plugin is greyed out, then it is not available for your product tier. See Kong Gateway tiers.
If the option is available, select Scoped.
Add the service name and ID to the Service field if it is not already prefilled.
Enter the following parameters, updating the default or sample values as needed:
- Config.Host: 127.0.0.1
- Config.Port: 8125
- Config.Metrics: All metrics are logged
- Config.Prefix: kong
- Config.Hostname In Prefix: clear checkbox
- Config.Udp Packet Size: ``0 (not combined)
- Config.Use Tcp: clear checkbox
- Config.Allow Status Codes: 200-205
- Config.Allow Status Codes: 400-499
Click Create.

The following examples provide some typical configurations for enabling the statsd-advanced plugin on a route.

Admin API

Kubernetes

Declarative (YAML)

Konnect Cloud

Kong Manager

Make the following request:

$ curl -X POST http://{HOST}:8001/routes/{ROUTE}/plugins \
    --data "name=statsd-advanced"  \
    --data "config.host=127.0.0.1" \
    --data "config.port=8125" \
    --data "config.metrics=All metrics are logged" \
    --data "config.prefix=kong" \
    --data "config.hostname_in_prefix=false" \
    --data "config.udp_packet_size=0 (not combined)" \
    --data "config.use_tcp=false" \
    --data "config.allow_status_codes=200-205" \
    --data "config.allow_status_codes=400-499"

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

First, create a KongPlugin resource:

apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: <statsd-advanced-example>
config: 
  host: 127.0.0.1
  port: 8125
  metrics: All metrics are logged
  prefix: kong
  hostname_in_prefix: false
  udp_packet_size: 0 (not combined)
  use_tcp: false
  allow_status_codes:
  - 200-205
  - 400-499
plugin: statsd-advanced

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

apiVersion: networking/v1beta1
kind: Ingress
metadata:
  name: {ROUTE}
  annotations:
    kubernetes.io/ingress.class: kong
    konghq.com/plugins: <statsd-advanced-example>
spec:
  rules:
  - host: examplehostname.com
    http:
      paths:
      - path: /bar
        backend:
          serviceName: echo
          servicePort: 80

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

Add this section to your declarative configuration file:

plugins:
- name: statsd-advanced
  route: <route>
  config: 
    host: 127.0.0.1
    port: 8125
    metrics: All metrics are logged
    prefix: kong
    hostname_in_prefix: false
    udp_packet_size: 0 (not combined)
    use_tcp: false
    allow_status_codes:
    - 200-205
    - 400-499

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

In Konnect Cloud, select the service from the ServiceHub page.
Scroll down to Versions and select the version.
Select the route.
Scroll down to Plugins and click Add Plugin.
Find and select the StatsD Advanced plugin.
Enter the following parameters, updating the default or sample values as needed:
- Config.Host: 127.0.0.1
- Config.Port: 8125
- Config.Metrics: All metrics are logged
- Config.Prefix: kong
- Config.Hostname In Prefix: clear checkbox
- Config.Udp Packet Size: ``0 (not combined)
- Config.Use Tcp: clear checkbox
- Config.Allow Status Codes: 200-205
- Config.Allow Status Codes: 400-499
Click Create.

In Kong Manager, select the workspace.
From the Dashboard, select Routes in the left navigation.
Click View for the route row.
Scroll down to plugins and click Add Plugin.
Find and select the StatsD Advanced plugin.

Note: If the plugin is greyed out, then it is not available for your product tier. See Kong Gateway tiers.
If the option is available, select Scoped.
Add the Route ID if it is not already prefilled.
Enter the following parameters, updating the default or sample values as needed:
- Config.Host: 127.0.0.1
- Config.Port: 8125
- Config.Metrics: All metrics are logged
- Config.Prefix: kong
- Config.Hostname In Prefix: clear checkbox
- Config.Udp Packet Size: ``0 (not combined)
- Config.Use Tcp: clear checkbox
- Config.Allow Status Codes: 200-205
- Config.Allow Status Codes: 400-499
Click Create.

The following examples provide some typical configurations for enabling the statsd-advanced plugin on a consumer.

Admin API

Kubernetes

Declarative (YAML)

Kong Manager

Make the following request:

$ curl -X POST http://{HOST}:8001/consumers/{CONSUMER}/plugins \
    --data "name=statsd-advanced"  \
    --data "config.host=127.0.0.1" \
    --data "config.port=8125" \
    --data "config.metrics=All metrics are logged" \
    --data "config.prefix=kong" \
    --data "config.hostname_in_prefix=false" \
    --data "config.udp_packet_size=0 (not combined)" \
    --data "config.use_tcp=false" \
    --data "config.allow_status_codes=200-205" \
    --data "config.allow_status_codes=400-499"

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 KongPlugin resource:

apiVersion: configuration.konghq.com/v1
kind: KongPlugin
metadata:
  name: <statsd-advanced-example>
config: 
  host: 127.0.0.1
  port: 8125
  metrics: All metrics are logged
  prefix: kong
  hostname_in_prefix: false
  udp_packet_size: 0 (not combined)
  use_tcp: false
  allow_status_codes:
  - 200-205
  - 400-499
plugin: statsd-advanced

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

apiVersion: configuration.konghq.com/v1
kind: KongConsumer
metadata:
  name: {CONSUMER}
  annotations:
    konghq.com/plugins: <statsd-advanced-example>
    kubernetes.io/ingress.class: kong

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.

Add this section to your declarative configuration file:

plugins:
- name: statsd-advanced
  consumer: {CONSUMER}
  config: 
    host: 127.0.0.1
    port: 8125
    metrics: All metrics are logged
    prefix: kong
    hostname_in_prefix: false
    udp_packet_size: 0 (not combined)
    use_tcp: false
    allow_status_codes:
    - 200-205
    - 400-499

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

In Kong Manager, select the workspace.
From the Dashboard, scroll down to Consumers and click View for the consumer row.
Select the Plugins tab.
Click Add Plugin.
Find and select the StatsD Advanced plugin.

Note: If the plugin is greyed out, then it is not available for your product tier. See Kong Gateway tiers.
If the option is available, select Global.
Enter the following parameters, updating the default or sample values as needed:
- Config.Host: 127.0.0.1
- Config.Port: 8125
- Config.Metrics: All metrics are logged
- Config.Prefix: kong
- Config.Hostname In Prefix: clear checkbox
- Config.Udp Packet Size: ``0 (not combined)
- Config.Use Tcp: clear checkbox
- Config.Allow Status Codes: 200-205
- Config.Allow Status Codes: 400-499
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 Plugin Precedence sections for more information.

The following examples provide some typical configurations for enabling the statsd-advanced plugin globally.

Admin API

Kubernetes

Declarative (YAML)

Kong Manager

Make the following request:

$ curl -X POST http://{HOST}:8001/plugins/ \
    --data "name=statsd-advanced"  \
    --data "config.host=127.0.0.1" \
    --data "config.port=8125" \
    --data "config.metrics=All metrics are logged" \
    --data "config.prefix=kong" \
    --data "config.hostname_in_prefix=false" \
    --data "config.udp_packet_size=0 (not combined)" \
    --data "config.use_tcp=false" \
    --data "config.allow_status_codes=200-205" \
    --data "config.allow_status_codes=400-499"

Create a KongClusterPlugin resource and label it as global:

apiVersion: configuration.konghq.com/v1
kind: KongClusterPlugin
metadata:
  name: <global-statsd-advanced>
  annotations:
    kubernetes.io/ingress.class: kong
  labels:
    global: \"true\"
config: 
  host: 127.0.0.1
  port: 8125
  metrics: All metrics are logged
  prefix: kong
  hostname_in_prefix: false
  udp_packet_size: 0 (not combined)
  use_tcp: false
  allow_status_codes:
  - 200-205
  - 400-499
plugin: statsd-advanced

Add a plugins entry in the declarative configuration file:

plugins:
- name: statsd-advanced
  config: 
    host: 127.0.0.1
    port: 8125
    metrics: All metrics are logged
    prefix: kong
    hostname_in_prefix: false
    udp_packet_size: 0 (not combined)
    use_tcp: false
    allow_status_codes:
    - 200-205
    - 400-499

In Kong Manager, select the workspace.
From the Dashboard, select Plugins in the left navigation.
Click New Plugin.
Find and select the StatsD Advanced plugin.

Note: If the plugin is greyed out, then it is not available for your product tier. See Kong Gateway tiers.
If the option is available, set the plugin scope to Global.
Enter the following parameters, updating the default/sample values as needed:
- Config.Host: 127.0.0.1
- Config.Port: 8125
- Config.Metrics: All metrics are logged
- Config.Prefix: kong
- Config.Hostname In Prefix: clear checkbox
- Config.Udp Packet Size: ``0 (not combined)
- Config.Use Tcp: clear checkbox
- Config.Allow Status Codes: 200-205
- Config.Allow Status Codes: 400-499
Click Create.

Parameters

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

Form Parameter	Description
`name` required Type: string	The name of the plugin, in this case `statsd-advanced`.
`service.id` Type: string	The ID of the Service the plugin targets.
`route.id` Type: string	The ID of the Route the plugin targets.
`consumer.id` Type: string	The ID of the Consumer the plugin targets.
`enabled` required Type: boolean Default value: `true`	Whether this plugin will be applied.
`config.host` required Type: string Default value: `127.0.0.1`	The IP address or hostname of StatsD server to send data to.
`config.port` required Type: integer Default value: `8125`	The port of StatsD server to send data to.
`config.metrics` required Type: Array of record elements Default value: `All metrics are logged`	List of Metrics to be logged. Available values are described under Metrics.
`config.prefix` required Type: string Default value: `kong`	String to prefix to each metric’s name.
`config.hostname_in_prefix` required Type: boolean Default value: `false`	Include the `hostname` in the `prefix` for each metric name.
`config.udp_packet_size` required Type: number Default value: `0 (not combined)`	Combine UDP packet up to the size configured. If zero (0), don’t combine the UDP packet. Must be a number between 0 and 65507 (inclusive).
`config.use_tcp` required Type: boolean Default value: `false`	Use TCP instead of UDP.
`config.allow_status_codes` required Type: array of string elements Default value: `All responses are passed to log metrics`	List of status code ranges that are allowed to be logged in metrics.

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

Metrics

Metric	Description	Namespace
`request_count`	the request count	kong.service.<service_identifier>.request.count
`request_size`	the request’s body size in bytes	kong.service.<service_identifier>.request.size
`response_size`	the response’s body size in bytes	kong.service.<service_identifier>.response.size
`latency`	the time interval in milliseconds between the request and response	kong.service.<service_identifier>.latency
`status_count`	tracks each status code returned in a response	kong.service.<service_identifier>.request.status.<status>.count and kong.<service_name>.request.status.<status>.total
`unique_users`	tracks unique users who made a requests to the underlying Service/Route	kong.service.<service_identifier>.user.uniques
`request_per_user`	tracks the request count per Consumer	kong.service.<service_identifier>.user.<consumer_id>.request.count
`upstream_latency`	tracks the time in milliseconds it took for the final Service to process the request	kong.service.<service_identifier>.upstream_latency
`kong_latency`	tracks the internal Kong latency in milliseconds that it took to run all the Plugins	kong.service.<service_identifier>.kong_latency
`status_count_per_user`	tracks the status code for per Consumer per Service	kong.<service_name>.user.<customer_id>.request.status.<status> and kong.<service_name>.user.<customer_id>.request.status.total
`status_count_per_workspace`	the status code per Workspace	kong.service.<service_identifier>.workspace.<workspace_identifier>.status.<status>
`status_count_per_user_per_route`	the status code per Consumer per Route	kong.route.<route_id>.user.<customer_id>.status.<status>
`shdict_usage`	the usage of shared dict, sent once every minute	kong.node.<node_hostname>.shdict.<shdict_name>.free_space and kong.node.<node_hostname>.shdict.<shdict_name>.capacity

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

Metric	Description	Namespace
`request_count`	the request count	kong.global.unmatched.request.count
`request_size`	the request’s body size in bytes	kong.global.unmatched.request.size
`response_size`	the response’s body size in bytes	kong.global.unmatched.response.size
`latency`	the time interval between the request started and response received from the upstream server	kong.global.unmatched.latency
`status_count`	the status count	kong.global.unmatched.status.<status>.count
`kong_latency`	the internal Kong latency in milliseconds that it took to run all the plugins	kong.global.unmatched.kong_latency

Metric Fields

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

Field	Description	Datatype	Allowed values
`name`	StatsD metric’s name. Required.	String	Metrics
`stat_type`	Determines what sort of event a metric represents. Required.	String	`gauge`, `timer`, `counter`, `histogram`, `meter` and `set`
`sample_rate` conditional	Sampling rate. Required.	Number	`number`
`consumer_identifier` conditional	Authenticated user detail. Required.	String	One of the following options: `consumer_id`, `custom_id`, `username`
`service_identifier` conditional	Service detail. Required.	String	One of the following options:`service_id`, `service_name`, `service_host`, `service_name_or_host`
`workspace_identifier` conditional	Workspace detail. Required.	String	One of the following options:`workspace_id`, `workspace_name`

Metric Behaviors

By default, all metrics get logged.
Metric with stat_type set to counter or gauge must have sample_rate defined as well.
unique_users metric only works with stat_type as set.
status_count, status_count_per_user, status_count_per_user_per_route and request_per_user work only with stat_type as counter.
shdict_usage work only with stat_type as gauge.
status_count_per_user, request_per_user, unique_users and status_count_per_user_per_route must have customer_identifier defined.
All metrics can optionally configure service_identifier; by default it’s set to service_name_or_host.
status_count_per_workspace must have workspace_identifier defined.

Kong Process Errors

This logging plugin logs HTTP request and response data, and also supports streams data (TCP, TLS, and UDP).

If you are looking for the Kong process error file (which is the nginx error file), you can find it at the following path:

{prefix}/logs/error.log

About this Plugin
Plugin Version	2.2.x
Made by	Kong Inc.
Categories	Logging
DB-less compatible?	Yes
Konnect Cloud compatible?	Yes
Compatible protocols	`http` `https` `grpc` `grpcs` `tcp` `tls` `udp`
Version Compatibility
Kong Gateway 2.8.x 2.7.x 2.6.x 2.5.x 2.4.x 2.3.x 2.2.x 2.1.x 1.5.x 1.3-x 0.36-x