Log metrics for a service or route to a local Datadog agent.
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 datadog . |
service.name or service.id
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 /plugins endpoint.
Not required if using /services/SERVICE_NAME|SERVICE_ID/plugins . |
route.name or route.id
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 /plugins endpoint.
Not required if using /routes/ROUTE_NAME|ROUTE_ID/plugins . |
consumer.name or consumer.id
Type: string |
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 /plugins endpoint.
Not required if using /consumers/CONSUMER_NAME|CONSUMER_ID/plugins . |
enabled
Type: boolean Default value: true |
Whether this plugin will be applied. |
config.host
optional Type: string Default value: localhost
|
The IP address or hostname to send data to. |
config.port
optional Type: integer Default value: 8125
|
The port to send data to on the upstream server. |
config.metrics
required Type: array of record elements |
List of metrics to be logged. Available values are described at Metrics. By default, the plugin logs all available metrics. If you specify an array of metrics, only the listed metrics are logged. |
config.prefix
optional Type: string Default value: kong
|
String to be attached as a prefix to a metric’s name. |
config.service_name_tag
optional Type: string Default value: name
|
String to be attached as the name of the service. |
config.status_tag
optional Type: string Default value: status
|
String to be attached as the tag of the HTTP status. |
config.consumer_tag
optional Type: string Default value: consumer
|
String to be attached as tag of the consumer. |
config.flush_timeout
required Type: number Default value: 2
|
Optional time in seconds. If |
config.retry_count
required Type: integer Default value: 10
|
Number of times to retry when sending data to the upstream server. |
config.queue_size
required Type: integer Default value: 1
|
Maximum number of log entries to be sent on each message to the upstream server. |
Metrics
The Datadog plugin currently logs the following metrics to the Datadog server about a service or route.
Metric | Description | Namespace |
---|---|---|
request_count |
tracks the request | kong.request.count |
request_size |
tracks the request’s body size in bytes | kong.request.size |
response_size |
tracks the response’s body size in bytes | kong.response.size |
latency |
tracks the time interval between the request started and response received from the upstream server | kong.latency |
upstream_latency |
tracks the time it took for the final service to process the request | kong.upstream_latency |
kong_latency |
tracks the internal Kong latency that it took to run all the plugins | kong.kong_latency |
The metrics will be sent with the tags name
and status
carrying the API name and HTTP status code respectively. If you specify consumer_identifier
with the metric, a tag consumer
will be added.
Metric fields
Plugin can be configured with any combination of Metrics, with each entry containing the following fields.
Field | Description | Datatypes | Allowed values |
---|---|---|---|
name |
Datadog metric’s name | String | Metrics |
stat_type |
Determines what sort of event the metric represents | String | gauge , timer , counter , histogram , meter , set , distribution |
sample_rate conditional |
Sampling rate | Number | number |
consumer_identifier conditional |
Authenticated user detail | String | consumer_id , custom_id , username |
tags optional |
List of tags | Array of strings | key[:value] |
Metric requirements
- All metrics get logged by default.
- Metrics with
stat_type
ascounter
orgauge
must havesample_rate
defined as well.
Migrating Datadog queries
The plugin updates replace the api, status, and consumer-specific metrics with a generic metric name. You must change your Datadog queries in dashboards and alerts to reflect the metrics updates.
For example, the following query:
avg:kong.sample_service.latency.avg{*}
would need to change to:
avg:kong.latency.avg{name:sample-service}
Setting host and port per Kong node basis
When installing a multi-data center setup, you might want to set Datadog’s agent host and port on a per Kong node basis. This configuration is possible by setting the host and port properties using environment variables.
Note:
host
andport
fields in the plugin config take precedence over environment variables.
Field | Description | Datatypes |
---|---|---|
KONG_DATADOG_AGENT_HOST |
The IP address or hostname to send data to. | string |
KONG_DATADOG_AGENT_PORT |
The port to send data to on the upstream server. | integer |
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.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 2.7.x
- Added support for the
distribution
metric type. - Allow service, consumer, and status tags to be customized through the configuration parameters
service_name_tag
,consumer_tag
, andstatus_tag
.
Kong Gateway 2.6.x
- The
host
andport
configuration options can now be configured through the environment variablesKONG_DATADOG_AGENT_HOST
andKONG_DATADOG_AGENT_PORT
. This lets you set different destinations for each Kong node, which makes multi-DC setups easier, and in Kubernetes, lets you run a Datadog agent as a DaemonSet.