You are browsing documentation for an outdated plugin version.
Looking for the plugin's configuration parameters? You can find them in the StatsD configuration reference doc.
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.
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.
Queueing
The StatsD plugin uses a queue to decouple the production and consumption of data. This reduces the number of concurrent requests made to the upstream server under high load situations and provides buffering during temporary network or upstream outages.
You can set several parameters to configure the behavior and capacity of the queues used by the plugin. For more information about how to use these parameters, see Plugin Queuing Reference in the Kong Gateway documentation.
The queue parameters all reside in a record under the key queue
in
the config
parameter section of the plugin.
Queues are not shared between workers and queueing parameters are scoped to one worker. For whole-system capacity planning, the number of workers need to be considered when setting queue parameters.
Metrics
Metric | Description | Namespace syntax |
---|---|---|
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 a shared dict, sent once every minute. Monitors any lua_shared_dict used by Kong Gateway. You can find all the shared dicts Kong Gateway has configured using the /status endpoint of the Admin API. For example, the metric might report on shdict.kong_locks or shdict.kong_counters . |
kong.node.<node_hostname>.shdict.<lua_shared_dict>.free_space and kong.node.<node_hostname>.shdict.<lua_shared_dict>.capacity
|
cache_datastore_hits_total |
The total number of cache hits. (Kong Gateway Enterprise only) | kong.service.<service_identifier>.cache_datastore_hits_total |
cache_datastore_misses_total |
The total number of cache misses. (Kong Gateway 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 Gateway Enterprise only) | kong.cache_datastore_hits_total |
cache_datastore_misses_total |
The total number of cache misses. (Kong Gateway 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 stream data (TCP, TLS, and UDP).
The Kong process error file is the Nginx error file. You can find it at the following path:
{prefix}/logs/error.log
Configure the prefix in
kong.conf
.