StatsD Advanced plugin

Kong Konnect only: This plugin is only available with a Kong Konnect subscription. Please inquire about Kong Konnect by contacting us.

Log metrics for a Service, Route (or the deprecated API entity) to a StatsD server. It can also be used to log metrics on Collectd daemon by enabling its StatsD plugin.

Tip: The StatsD Advanced plugin provides additional 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 requests with the following protocols:

http
https
grpc
grpcs
tcp
tls
udp

Enabling the plugin on a service

Admin API

Kubernetes

Declarative (YAML)

Konnect SaaS

Manager

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

$ curl -X POST http://<admin-hostname>: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.

For example, configure this plugin on a service by adding 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.

Configure this plugin on a service:

In Konnect SaaS, 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.

Configure this plugin on a service:

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.

Enabling the plugin on a route

Admin API

Kubernetes

Declarative (YAML)

Konnect SaaS

Manager

For example, configure this plugin on a route with:

$ curl -X POST http://<admin-hostname>: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.

For example, configure this plugin on a route by adding 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.

Configure this plugin on a route:

In Konnect SaaS, 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.

Configure this plugin on a route:

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.

Enabling the plugin on a consumer

Admin API

Kubernetes

Declarative (YAML)

Manager

For example, configure this plugin on a consumer with:

$ curl -X POST http://<admin-hostname>: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.

For example, configure this plugin on a consumer by adding 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.

Configure this plugin on a consumer:

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.

Enabling the plugin globally

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.

Admin API

Kubernetes

Declarative (YAML)

Kong Manager

For example, configure this plugin globally with:

$ curl -X POST http://<admin-hostname>: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

For example, configure this plugin using the 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

Configure this plugin globally:

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` Type: string	The name of the plugin to use, 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` 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 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 it took for the final Service to process the request	kong.service.<service_identifier>.upstream_latency
`kong_latency`	tracks the internal Kong latency 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 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
Made by
Categories	Logging
Version Compatibility
Kong Gateway (Enterprise) 2.3.x 2.2.x 2.1.x 1.5.x 1.3-x 0.36-x