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.
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
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 . |
instance_name
optional Type: string |
An optional custom name to identify an instance of the plugin, for example Useful when running the same plugin in multiple contexts, for example, on multiple services. |
service.name or service.id
optional Type: string |
The name or ID of the service the plugin targets. Set one of these parameters if adding the plugin to a service through the top-level Not required if using |
route.name or route.id
optional Type: string |
The name or ID of the route the plugin targets. Set one of these parameters if adding the plugin to a route through the top-level Not required if using |
consumer.name or consumer.id
optional
|
The name or ID of the consumer the plugin targets. Set one of these parameters if adding the plugin to a consumer through the top-level Not required if using |
enabled
optional Type: boolean Default value: |
Whether this plugin will be applied. |
config.host
required Type: string Default value: |
The IP address or hostname of StatsD server to send data to. |
config.port
required Type: integer Default value: |
The port of StatsD server to send data to. |
config.metrics
required Type: Array of record elements Default value: |
List of metrics to be logged. Available values are described under Metrics. |
config.prefix
required Type: string Default value: |
String to prefix to each metric’s name. |
config.hostname_in_prefix
required Type: boolean Default value: |
Include the |
config.udp_packet_size
required Type: number Default value: |
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: |
Use TCP instead of UDP. |
config.allow_status_codes
required Type: array of string elements Default value: |
List of status code ranges that are allowed to be logged in metrics. |
config.consumer_identifier_default
required Type: string Default value: |
The default consumer identifier of metrics. This takes effect when a metric’s consumer identifier is omitted. Allowed values are |
config.service_identifier_default
required Type: string Default value: |
The default service identifier of metrics. This takes effect when a metric’s service identifier is omitted. Allowed values are |
config.workspace_identifier_default
required Type: string Default value: |
The default workspace identifier of metrics. This will take effect when a metric’s workspace identifier is omitted. Allowed values are |
config.flush_timeout
required Type: number Default value: |
Optional time in seconds. If |
config.retry_count
required Type: integer Default value: |
Number of times to retry when sending data to the upstream server. |
config.queue_size
required Type: integer Default value: |
Maximum number of log entries to be sent on each message to the upstream server. |
config.tag_style
optional Type: string |
The tag style configurations to send metrics with tags. Defaults to |
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. Consider the MTU of the network when setting this parameter.
Metrics
Metric | Description | Namespace |
---|---|---|
request_count |
The number of requests. | 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>.status.<status> |
unique_users |
Tracks unique users who made requests to the underlying Service or route. | kong.service.<service_identifier>.user.uniques |
request_per_user |
Tracks the request count per consumer. | kong.service.<service_identifier>.user.<consumer_identifier>.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 per consumer per service. | kong.service.<service_identifier>.user.<consumer_identifier>.status.<status> |
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.<consumer_identifier>.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 |
cache_datastore_hits_total |
The total number of cache hits. (Kong Enterprise only) | kong.service.<service_identifier>.cache_datastore_hits_total |
cache_datastore_misses_total |
The total number of cache misses. (Kong Enterprise only) | kong.service.<service_identifier>.cache_datastore_misses_total |
If a request URI doesn’t match any Routes, the following metrics are 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 when the request started and when the response is 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 |
If you enable the tag_style
configuration for the StatsD plugin, the following metrics are sent instead:
Metric | Description | Namespace |
---|---|---|
request_count |
The number of requests. | kong.request.count |
request_size |
The request’s body size in bytes. | kong.request.size |
response_size |
The response’s body size in bytes. | kong.response.size |
latency |
The time interval in milliseconds between the request and response. | kong.latency |
request_per_user |
Tracks the request count per consumer. | kong.request.count |
upstream_latency |
Tracks the time in milliseconds it took for the final service to process the request. | kong.upstream_latency |
shdict_usage |
The usage of shared dict, sent once every minute. | kong.shdict.free_space and kong.shdict.capacity |
cache_datastore_hits_total |
The total number of cache hits. (Kong Enterprise only) | kong.cache_datastore_hits_total |
cache_datastore_misses_total |
The total number of cache misses. (Kong Enterprise only) | kong.cache_datastore_misses_total |
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 the tag_style
config 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 plugin can be configured with any combination of Metrics, with each entry containing the following fields:
Field | Description | Datatype | Allowed values |
---|---|---|---|
name required |
StatsD metric’s name. | String | Metrics |
stat_type required |
Determines what sort of event a metric represents. | String | gauge , timer , counter , histogram , meter and set |
sample_rate required conditional |
Sampling rate. | Number | number |
consumer_identifier conditional |
Authenticated user detail. | String | One of the following options: consumer_id , custom_id , username , null |
service_identifier conditional |
Service detail. | String | One of the following options: service_id , service_name , service_host , service_name_or_host , null |
workspace_identifier conditional |
Workspace detail. | String | One of the following options:workspace_id , workspace_name , null |
Metric behaviors
- By default, all metrics get logged.
- Metric with
stat_type
set tocounter
orgauge
must havesample_rate
defined as well. unique_users
metric only works withstat_type
asset
.status_count
,status_count_per_user
,status_count_per_user_per_route
andrequest_per_user
work only withstat_type
ascounter
.shdict_usage
work only withstat_type
asgauge
.status_count_per_user
,request_per_user
,unique_users
andstatus_count_per_user_per_route
must havecustomer_identifier
defined.- All metrics can optionally configure
service_identifier
; by default it’s set toservice_name_or_host
. status_count_per_workspace
must haveworkspace_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
Changelog
Kong Gateway 3.2.x
- Added the
tag_style
configuration parameter. This allows you to send metrics with tags. Defaults tonil
, which doesn’t add any tags to the metrics.
Kong Gateway 3.1.x
- Added support for managing queues and connection retries when sending messages to the upstream with
the
queue_size
,flush_timeout
, andretry_count
configuration parameters.
Kong Gateway 3.0.x
- Merged features of the StatsD Advanced plugin into the StatsD plugin. The StatsD plugin now includes the following:
- New parameters for StatsD:
hostname_in_prefix
,udp_packet_size
,ues_tcp
,allow_status_codes
,consumer_identifier_default
,service_identifier_default
,workspace_identifier_default
. - New metrics:
status_count_per_workspace
,status_count_per_user_per_route
,shdict_usage
- New metric fields:
service_identifier
,workspace_identifier
- New parameters for StatsD:
- Breaking changes
- The metric name that is related to the service has been renamed by adding a
service.
prefix. e.g.kong.service.<service_identifier>.request.count
- The metric
kong.<service_identifier>.request.status.<status>.count
from metricsstatus_count
andstatus_count_per_user
has been renamed tokong.service.<service_identifier>.status.<status>.count
- The metric
*.status.<status>.total
from metricsstatus_count
andstatus_count_per_user
has been removed. - The metric
kong.<service_identifier>.request_size
andkong.<service_identifier>.response_size
stat type has been changed fromtimer
tocounter
.
- The metric name that is related to the service has been renamed by adding a