Log metrics for a Service, Route to a local
Datadog agent.
Note: The functionality of this plugin as bundled
with versions of Kong prior to 1.4.0 differs from what is documented herein.
Refer to the
CHANGELOG
for details.
Configuration Reference
This plugin is not compatible with DB-less mode.
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://{HOST}:8001/services/{SERVICE}/plugins \
--data "name=datadog" \
--data "config.host=127.0.0.1" \
--data "config.port=8125" \
--data "config.metrics=" \
--data "config.prefix=kong"
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: <datadog-example>
config:
host: 127.0.0.1
port: 8125
metrics:
prefix: kong
plugin: datadog
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: <datadog-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
.
Add this section to your declarative configuration file:
plugins:
- name: datadog
service: {SERVICE}
config:
host: 127.0.0.1
port: 8125
metrics:
prefix: kong
SERVICE
is the id
or name
of the service that this plugin
configuration will target.
- 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 Datadog 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: ``
- Config.Prefix:
kong
- 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://{HOST}:8001/routes/{ROUTE}/plugins \
--data "name=datadog" \
--data "config.host=127.0.0.1" \
--data "config.port=8125" \
--data "config.metrics=" \
--data "config.prefix=kong"
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: <datadog-example>
config:
host: 127.0.0.1
port: 8125
metrics:
prefix: kong
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}
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
ROUTE
is 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>
config:
host: 127.0.0.1
port: 8125
metrics:
prefix: kong
ROUTE
is the id
or name
of the route that this plugin configuration
will target.
- 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 Datadog 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: ``
- Config.Prefix:
kong
- 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://{HOST}:8001/consumers/{CONSUMER}/plugins \
--data "name=datadog" \
--data "config.host=127.0.0.1" \
--data "config.port=8125" \
--data "config.metrics=" \
--data "config.prefix=kong"
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: <datadog-example>
config:
host: 127.0.0.1
port: 8125
metrics:
prefix: kong
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}
annotations:
konghq.com/plugins: <datadog-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
.
Add this section to your declarative configuration file:
plugins:
- name: datadog
consumer: {CONSUMER}
config:
host: 127.0.0.1
port: 8125
metrics:
prefix: kong
CONSUMER
is the id
or username
of the consumer that this plugin
configuration will target.
- 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 Datadog 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: ``
- Config.Prefix:
kong
- 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://{HOST}:8001/plugins/ \
--data "name=datadog" \
--data "config.host=127.0.0.1" \
--data "config.port=8125" \
--data "config.metrics=" \
--data "config.prefix=kong"
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
metrics:
prefix: kong
plugin: datadog
Add a plugins
entry in the declarative
configuration file:
plugins:
- name: datadog
config:
host: 127.0.0.1
port: 8125
metrics:
prefix: kong
- In Kong Manager, select the workspace.
- From the Dashboard, select Plugins in the left navigation.
- Click New Plugin.
-
Find and select the Datadog 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: ``
- Config.Prefix:
kong
- 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.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
required
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.
|
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 and set |
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}
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