Log metrics for a Service, 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
Enable on a service
Enable on a route
Enable on a consumer
Enable globally
The following examples provide some typical configurations for enabling
the datadog
plugin on a
service.
Admin API
Kubernetes
Declarative (YAML)
Kong Manager
Make the following request:
curl -X POST http://localhost:8001/services/SERVICE_NAME|SERVICE_ID/plugins \
--data "name=datadog" \
--data "config.host=127.0.0.1" \
--data "config.port=8125"
Replace SERVICE_NAME|SERVICE_ID
with 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: datadog-example
config:
host: 127.0.0.1
port: 8125
plugin: datadog
Next, apply the KongPlugin resource to a
service by annotating the
service as follows:
apiVersion: v1
kind: Service
metadata:
name: SERVICE_NAME|SERVICE_ID
labels:
app: SERVICE_NAME|SERVICE_ID
annotations:
konghq.com/plugins: datadog-example
spec:
ports:
- port: 80
targetPort: 80
protocol: TCP
name: SERVICE_NAME|SERVICE_ID
selector:
app: SERVICE_NAME|SERVICE_ID
Replace SERVICE_NAME|SERVICE_ID
with 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: datadog
service: SERVICE_NAME|SERVICE_ID
config:
host: 127.0.0.1
port: 8125
Replace SERVICE_NAME|SERVICE_ID
with the id
or name
of the service that this plugin configuration will target.
You can configure this plugin through the Kong Manager UI.
- In Kong Manager, select the workspace.
- From the Services section, click View for the
service row.
- From the plugin section, click Add Plugin.
- Find and select the Datadog plugin.
- If the option is available, select Scoped.
- Add the service name and ID to the Service field if it
is not already pre-filled.
-
Configure the plugin’s parameters.
You can test out the plugin with the following sample configuration:
- Config.Host:
127.0.0.1
- Config.Port:
8125
- Click Create.
The following examples provide some typical configurations for enabling
the datadog
plugin on a
route.
Admin API
Kubernetes
Declarative (YAML)
Kong Manager
Make the following request:
$ curl -X POST http://localhost:8001/routes/ROUTE_NAME|ROUTE_ID/plugins \
--data "name=datadog" \
--data "config.host=127.0.0.1" \
--data "config.port=8125"
Replace ROUTE_NAME|ROUTE_ID
with 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: datadog-example
config:
host: 127.0.0.1
port: 8125
plugin: datadog
Then, apply it to an ingress (route or routes)
by annotating the ingress as follows:
apiVersion: networking/v1beta1
kind: Ingress
metadata:
name: ROUTE_NAME|ROUTE_ID
annotations:
kubernetes.io/ingress.class: kong
konghq.com/plugins: datadog-example
spec:
rules:
- host: examplehostname.com
http:
paths:
- path: /bar
backend:
serviceName: echo
servicePort: 80
Replace ROUTE_NAME|ROUTE_ID
with the id
or name
of the route 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: datadog
route: ROUTE_NAME
config:
host: 127.0.0.1
port: 8125
Replace ROUTE_NAME|ROUTE_ID
with the id
or name
of the route that this plugin configuration
will target.
You can configure this plugin through the Kong Manager UI.
- In Kong Manager, select the workspace.
- Open Routes from the menu, then click View for the
route row.
- From the plugin section, click Add Plugin.
- Find and select the Datadog plugin.
- If the option is available, select Scoped.
- Add the route ID if it is not already prefilled.
-
Configure the plugin’s parameters.
You can test out the plugin with the following sample configuration:
- Config.Host:
127.0.0.1
- Config.Port:
8125
- Click Create.
The following examples provide some typical configurations for enabling
the datadog
plugin on a
consumer.
Admin API
Kubernetes
Declarative (YAML)
Kong Manager
Make the following request:
$ curl -X POST http://localhost:8001/consumers/CONSUMER_NAME|CONSUMER_ID/plugins \
--data "name=datadog" \
--data "config.host=127.0.0.1" \
--data "config.port=8125"
Replace CONSUMER_NAME|CONSUMER_ID
with the id
or name
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: datadog-example
config:
host: 127.0.0.1
port: 8125
plugin: datadog
Then, apply it to a consumer by
annotating the KongConsumer resource as follows:
apiVersion: configuration.konghq.com/v1
kind: KongConsumer
metadata:
name: CONSUMER_NAME|CONSUMER_ID
annotations:
konghq.com/plugins: datadog-example
kubernetes.io/ingress.class: kong
Replace CONSUMER_NAME|CONSUMER_ID
with the id
or name
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: datadog
consumer: CONSUMER_NAME|CONSUMER_ID
config:
host: 127.0.0.1
port: 8125
Replace CONSUMER_NAME|CONSUMER_ID
with the id
or name
of the consumer that this plugin configuration will target.
You can configure this plugin through the Kong Manager UI.
- In Kong Manager, select the workspace.
- From the Consumers section, click View for the consumer row.
- Select the Plugins tab, then click Add Plugin.
- Find and select the Datadog plugin.
- If the option is available, select Scoped.
- Add the consumer ID if it is not already prefilled.
-
Configure the plugin’s parameters.
You can test out the plugin with the following sample configuration:
- Config.Host:
127.0.0.1
- Config.Port:
8125
- 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 datadog
plugin globally.
Admin API
Kubernetes
Declarative (YAML)
Kong Manager
Make the following request:
$ curl -X POST http://localhost:8001/plugins/ \
--data "name=datadog" \
--data "config.host=127.0.0.1" \
--data "config.port=8125"
Create a KongClusterPlugin
resource and label it as global:
apiVersion: configuration.konghq.com/v1
kind: KongClusterPlugin
metadata:
name: <global-datadog>
annotations:
kubernetes.io/ingress.class: kong
labels:
global: \"true\"
config:
host: 127.0.0.1
port: 8125
plugin: datadog
Add a plugins
entry in the declarative
configuration file:
plugins:
- name: datadog
config:
host: 127.0.0.1
port: 8125
You can configure this plugin through the Kong Manager UI.
- In Kong Manager, select the workspace.
- Open Plugins from the menu, then click New Plugin.
- Find and select the Datadog plugin.
- If the option is available, set the plugin scope to Global.
-
Configure the plugin’s parameters.
You can test out the plugin with the following sample configuration:
- Config.Host:
127.0.0.1
- Config.Port:
8125
- 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 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
required
Type: string
Default value: localhost
|
The IP address or host name to send data to.
|
config.port
required
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
required
Type: string
Default value: kong
|
String to be attached as prefix to metric’s name.
|
config.service_name_tag
optional
Type: string
Default value: name
|
String to be attached as name of the service.
|
config.status_tag
optional
Type: string
Default value: status
|
String to be attached as name of the http status.
|
config.consumer_tag
optional
Type: string
Default value: consumer
|
String to be attached as name of the consumer.
|
Changes in this version
- New stat type:
distribution
- New configuration options:
consumer_tag
, status_tag
, service_name_tag
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 , and 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
as counter
or gauge
must have sample_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
and port
fields in the plugin config take precedence over environment variables.
Field |
Description |
Datatypes |
KONG_DATADOG_AGENT_HOST |
The IP address or host name 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