datadog

Sends request metrics to a Datadog agent.

Category ObservabilityAdd it to Route, Service, Consumer, Consumer group, Global rule, Plugin configEngine plugin datadogPriority 495

What it does

datadog sends no request records. It sends metrics about the requests that reach the route or other object it is added to, a request counter for example, to a Datadog agent over UDP. The agent's Host and Port are set once in the plugin metadata, for every route that carries the plugin.

Each metric carries tags. The tags of the plugin metadata come first, then the route's Constant tags, the route's name, and with Include method and Include path the method and the matched path. A route's tags are added to those of the metadata, never in their place.

When to use it

• The operations team watches the gateway in Datadog, beside the dashboards of the services behind it.
• Each team should see the request counts of its own routes, tagged team:payments for the payments team for example.
• The orders API's metrics should be split by method and by the path a route matched on.
• A Datadog agent runs on the gateway network at 10.0.5.10, and every route should report to it under the prefix gateway.

Not for metrics that Prometheus collects from the gateway — see prometheus (Exposes request metrics for Prometheus), a record of each request sent to an HTTP collector — see http-logger (Sends request logs to an HTTP endpoint in batches) or a record of each request kept in Elasticsearch — see elasticsearch-logger (Sends request logs to an Elasticsearch index).

Set it up

Send request metrics tagged with the route and its method

Under Basics fill Constant tags as in the JSON below, turn on Include method and turn on Include path.

datadog · as the console saves it

{
  "constant_tags": [
    "env:production",
    "team:payments"
  ],
  "include_method": true,
  "include_path": true
}

More scenarios

Point every route that carries the plugin at the Datadog agent on the gateway networkenvironment-wide settings

Fill Constant tags as in the JSON below, set Host to 10.0.5.10, set Namespace to gateway and leave Port at 8125.

datadog environment-wide settings · as the console saves it

{
  "host": "10.0.5.10",
  "port": 8125,
  "namespace": "gateway",
  "constant_tags": [
    "source:gateway",
    "env:production"
  ]
}

Things to know

• Constant tags — On each metric the route's tags follow those of the plugin metadata. In the example a metric carries env:production and team:payments after the metadata's source tag.
• Constant tags — A tag that starts with a digit, 1zz for example, is refused when you save.
• Constant tags — These are added to the tags the metadata carries, never in place of them.
• Include method — With Include method and Include path on, each metric carries a path tag and a method tag, method:GET for a GET.
• Prefer name — A service with no name sends no service_name tag at all.
• In the plugin metadata, Host and Port name the agent, and the metrics reach it over UDP.
• Host — Every route that carries this plugin sends its metrics to this one agent address; a route cannot name another.
• In the plugin metadata, Namespace is put in front of each metric name. With gateway the request counter arrives as gateway.request.counter.
• Batch size — A batch goes out when it holds Batch size metrics, when its first one has waited Buffer duration, or when nothing new arrived for Inactive timeout.
• In the plugin metadata, Pending entry limit caps the backlog. While more entries than this wait to be sent, new ones are dropped rather than queued.
• AdvicePut the tags every route shares, the environment for example, in the plugin metadata, and keep a route's own tags for what sets it apart, as the examples do.

Settings

The fields as the console shows them, section by section.

Basics

Constant tagsconstant_tagsarray of stringsdefault []

Tags added to every metric, written as key:value such as env:prod.

each 1 to 200 characters

Include methodinclude_methodbooleandefault false

Adds a method tag to every metric of this route.

Include pathinclude_pathbooleandefault false

Adds a path tag carrying the path the route matched on, which is not the request's own URI.

Behavior

Prefer nameprefer_namebooleandefault true

On, the route_name tag carries the route's name, or its id when it has none. A service with no name sends no service_name tag at all.

Advanced

Batch sizebatch_max_sizeintegerdefault 1000

at least 1

Buffer durationbuffer_durationintegerdefault 60

at least 1 · in seconds

Inactive timeoutinactive_timeoutintegerdefault 5

at least 1 · in seconds

Retriesmax_retry_countintegerdefault 0

at least 0

Retry delayretry_delayintegerdefault 1

at least 0 · in seconds

Namenamestringdefault datadog

Environment-wide settings

Set once per environment, under Plugins › datadog. Every datadog in the environment uses these.

Constant tagsconstant_tagsarray of stringsdefault ["source:apisix"]

Sent on every metric of every route; a route's own tags are added to these, never in place of them.

each 1 to 200 characters

Hosthoststringdefault 127.0.0.1

Pending entry limitmax_pending_entriesintegerdefault 8192

How many log entries may wait to be sent. While the backlog is above this number, new entries are dropped rather than queued.

at least 1

Namespacenamespacestringdefault apisix

Put in front of every metric name with a dot between; empty sends the names unprefixed.

Portportintegerdefault 8125

at least 0

Every plugin also has Enabled, Priority, Filter, Error response and Pre-function: see Plugin execution settings.