apache · Yilialinn · Apr 28, 2026 · Apr 21, 2026 · Apr 22, 2026 · Apr 22, 2026
diff --git a/docs/en/latest/plugins/datadog.md b/docs/en/latest/plugins/datadog.md
@@ -5,7 +5,7 @@ keywords:
   - API Gateway
   - Plugin
   - Datadog
-description: This document contains information about the Apache APISIX datadog Plugin.
+description: The datadog Plugin integrates with Datadog, sending metrics to DogStatsD in batches to improve API monitoring and performance tracking.
 ---
 
 <!--
@@ -27,144 +27,162 @@ description: This document contains information about the Apache APISIX datadog
 #
 -->
 
-## Description
-
-The `datadog` monitoring Plugin is for seamless integration of APISIX with [Datadog](https://www.datadoghq.com/), one of the most used monitoring and observability platform for cloud applications.
-
-When enabled, the Plugin supports multiple metric capture types for request and response cycles.
+<head>
+  <link rel="canonical" href="https://docs.api7.ai/hub/datadog" />
+</head>
 
-This Plugin, pushes its custom metrics to the [DogStatsD](https://docs.datadoghq.com/developers/dogstatsd/?tab=hostagent) server over UDP protocol and comes bundled with [Datadog agent](https://docs.datadoghq.com/agent/).
+## Description
 
-DogStatsD implements the StatsD protocol which collects the custom metrics for the Apache APISIX agent, aggregates them into a single data point, and sends it to the configured Datadog server.
+The `datadog` Plugin supports integration with [Datadog](https://www.datadoghq.com/), one of the most widely used observability services for cloud applications. When enabled, the Plugin pushes metrics to the [DogStatsD](https://docs.datadoghq.com/developers/dogstatsd/?tab=hostagent) server, which comes bundled with the [Datadog agent](https://docs.datadoghq.com/agent/), over UDP protocol.
 
-This Plugin provides the ability to push metrics as a batch to the external Datadog agent, reusing the same datagram socket. It might take some time to receive the log data. It will be automatically sent after the timer function in the [batch processor](../batch-processor.md) expires.
+This Plugin provides the ability to push metrics as a batch to the external Datadog agent over UDP. It might take some time to receive the metric data. It will be automatically sent after the timer function in the [batch processor](../batch-processor.md) expires.
 
 ## Attributes
 
-| Name           | Type    | Required | Default | Valid values | Description                                                                                                      |
-| -------------- | ------- | -------- | ------- | ------------ | ---------------------------------------------------------------------------------------------------------------- |
-| prefer_name    | boolean | False    | true    | [true,false] | When set to `false`, uses Route/Service ID instead of name (default) with metric tags.                           |
-| include_path   | boolean | False    | false   | [true,false] | When set to `true`, includes the path pattern in metric tags.                                                    |
-| include_method | boolean | False    | false   | [true,false] | When set to `true`, includes the HTTP method in metric tags.                                                     |
-| constant_tags  | array   | False    | []      |              | Static tags to embed into all metrics generated by this route. Useful for grouping metrics over certain signals. |
+| Name           | Type    | Required | Default | Valid values   | Description                                                                                                              |
+| -------------- | ------- | -------- | ------- | -------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| prefer_name    | boolean | False    | true    | [true, false]  | If true, exports Route/Service name instead of their ID in metric tags.                                                  |
+| include_path   | boolean | False    | false   | [true, false]  | If true, includes the path pattern in metric tags.                                                                       |
+| include_method | boolean | False    | false   | [true, false]  | If true, includes the HTTP method in metric tags.                                                                        |
+| constant_tags  | array   | False    | []      |                | Static key-value tags attached to all metrics generated by this Route. Useful for grouping metrics over certain signals. |
+| batch_max_size | integer | False    | 1000    | [1,...]        | Maximum number of metric entries per batch. Once reached, the batch is sent to the Datadog agent. Set to `1` for immediate processing. |
+| inactive_timeout | integer | False  | 5       | [1,...]        | Maximum time in seconds to wait for new metric entries before sending the batch. The value should be smaller than `buffer_duration`. |
+| buffer_duration | integer | False   | 60      | [1,...]        | Maximum time in seconds from the earliest metric entry allowed before sending the batch.                                 |
+| retry_delay    | integer | False    | 1       | [0,...]        | Time interval in seconds to retry sending the batch if the previous attempt failed.                                      |
+| max_retry_count | integer | False   | 0       | [0,...]        | Maximum number of unsuccessful retries before dropping the metric entries.                                               |
 
-This Plugin supports using batch processors to aggregate and process entries (logs/data) in a batch. This avoids the need for frequently submitting the data. The batch processor submits data every `5` seconds or when the data in the queue reaches `1000`. See [Batch Processor](../batch-processor.md#configuration) for more information or setting your custom configuration.
+This Plugin supports using batch processors to aggregate and process metric data in a batch. This avoids the need to submit data too frequently. The batch processor submits data every `5` seconds or when the data in the queue reaches `1000`. See [Batch Processor](../batch-processor.md#configuration) for more information or to customize the configuration.
 
-## Metadata
+## Plugin Metadata
 
-You can configure the Plugin through the Plugin metadata.
+You can configure the Plugin through Plugin metadata.
 
 | Name          | Type    | Required | Default             | Description                                                                                                                               |
 | ------------- | ------- | -------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
 | host          | string  | False    | "127.0.0.1"         | DogStatsD server host address.                                                                                                            |
-| port          | integer | False    | 8125                | DogStatsD server host port.                                                                                                               |
-| namespace     | string  | False    | "apisix"            | Prefix for all custom metrics sent by APISIX agent. Useful for finding entities for metrics graph. For example, `apisix.request.counter`. |
-| constant_tags | array   | False    | [ "source:apisix" ] | Static tags to embed into generated metrics. Useful for grouping metrics over certain signals.                                            |
+| port          | integer | False    | 8125                | DogStatsD server port.                                                                                                                    |
+| namespace     | string  | False    | "apisix"            | Prefix for all custom metrics sent by the APISIX agent. Useful for finding entities for metrics graph. For example, `apisix.request.counter`. |
+| constant_tags | array   | False    | [ "source:apisix" ] | Static tags to embed into generated metrics. Useful for grouping metrics over certain signals. See [defining tags](https://docs.datadoghq.com/getting_started/tagging/#defining-tags) for more. |
 
-:::tip
+## Metrics
 
-See [defining tags](https://docs.datadoghq.com/getting_started/tagging/#defining-tags) to know more about how to effectively use tags.
+The Plugin exports the following metrics by default.
 
-:::
+All metrics will be prefixed by the `namespace` configured in metadata. For example, if `namespace` is set to `apisix`, the `request.counter` metric will be exported as `apisix.request.counter` in Datadog.
 
-By default, the Plugin expects the DogStatsD service to be available at `127.0.0.1:8125`. If you want to change this, you can update the Plugin metadata as shown below:
+| Name             | StatsD Type | Description                                                                                           |
+| ---------------- | ----------- | ----------------------------------------------------------------------------------------------------- |
+| request.counter  | Counter     | Number of requests received.                                                                          |
+| request.latency  | Histogram   | Time taken to process the request, in milliseconds.                                                   |
+| upstream.latency | Histogram   | Time taken to proxy the request to the upstream server until a response is received, in milliseconds. |
+| apisix.latency   | Histogram   | Time taken by the APISIX agent to process the request, in milliseconds.                               |
+| ingress.size     | Timer       | Request body size in bytes.                                                                           |
+| egress.size      | Timer       | Response body size in bytes.                                                                          |
 
-:::note
-You can fetch the `admin_key` from `config.yaml` and save to an environment variable with the following command:
+## Tags
 
-```bash
-admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')
-```
+The Plugin exports metrics with the following [tags](https://docs.datadoghq.com/getting_started/tagging). When there are no suitable values for any particular tag, the tag will be omitted.
 
-:::
+| Name                  | Description                                                                                                                   |
+| --------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| route_name            | Name of the Route. If not present or if the attribute `prefer_name` is set to false, falls back to the Route ID.              |
+| service_name          | Name of the Service. If not present or if the attribute `prefer_name` is set to false, falls back to the Service ID.          |
+| consumer              | Username of the Consumer if the Route is connected to a Consumer.                                                             |
+| balancer_ip           | IP address of the upstream balancer that processes the current request.                                                       |
+| response_status       | HTTP response status code, such as `201`, `404`, or `503`.                                                                    |
+| response_status_class | HTTP response status code class, such as `2xx`, `4xx`, or `5xx`. Available from APISIX version 3.14.0.                       |
+| scheme                | Request scheme, such as HTTP and gRPC.                                                                                        |
+| path                  | HTTP path pattern. Only available if the attribute `include_path` is set to `true`. Available from APISIX version 3.14.0.     |
+| method                | HTTP method. Only available if the attribute `include_method` is set to `true`. Available from APISIX version 3.14.0.         |
 
-```shell
-curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/datadog -H "X-API-KEY: $admin_key" -X PUT -d '
-{
-    "host": "172.168.45.29",
-    "port": 8126,
-    "constant_tags": [
-        "source:apisix",
-        "service:custom"
-    ],
-    "namespace": "apisix"
-}'
-```
+## Examples
 
-To reset to default configuration, make a PUT request with empty body:
+The following examples demonstrate how you can configure the `datadog` Plugin for different scenarios.
 
-```shell
-curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/datadog -H "X-API-KEY: $admin_key" -X PUT -d '{}'
-```
+Before proceeding, make sure you have installed the [Datadog agent](https://docs.datadoghq.com/agent/), which collects events and metrics from monitored objects and sends them to Datadog.
 
-## Exported metrics
+Start the Datadog agent with your API key, Datadog site, and hostname. Set `DD_DOGSTATSD_NON_LOCAL_TRAFFIC` to `true` to listen to DogStatsD packets from other containers:
 
-When the `datadog` Plugin is enabled, the APISIX agent exports the following metrics to the DogStatsD server for each request/response cycle:
+```shell
+docker run -d \
+  --name dogstatsd-agent \
+  -e DD_API_KEY=<your-api-key> \
+  -e DD_SITE="us5.datadoghq.com" \
+  -e DD_HOSTNAME=apisix.quickstart \
+  -e DD_DOGSTATSD_NON_LOCAL_TRAFFIC=true \
+  -p 8125:8125/udp \
+  datadog/dogstatsd:latest
+```
 
-| Metric name      | StatsD type | Description                                                                                           |
-| ---------------- | ----------- | ----------------------------------------------------------------------------------------------------- |
-| Request Counter  | Counter     | Number of requests received.                                                                          |
-| Request Latency  | Histogram   | Time taken to process the request (in milliseconds).                                                  |
-| Upstream latency | Histogram   | Time taken to proxy the request to the upstream server till a response is received (in milliseconds). |
-| APISIX Latency   | Histogram   | Time taken by APISIX agent to process the request (in milliseconds).                                  |
-| Ingress Size     | Timer       | Request body size in bytes.                                                                           |
-| Egress Size      | Timer       | Response body size in bytes.                                                                          |
-
-The metrics will be sent to the DogStatsD agent with the following tags:
-
-- `route_name`: Name specified in the Route schema definition. If not present or if the attribute `prefer_name` is set to false, falls back to the Route ID.
-- `service_name`: If a Route has been created with an abstracted Service, the Service name/ID based on the attribute `prefer_name`.
-- `consumer`: If the Route is linked to a Consumer, the username will be added as a tag.
-- `balancer_ip`: IP address of the Upstream balancer that processed the current request.
-- `response_status`: HTTP response status code. E.g. "200", "404", "503".
-- `response_status_class`: HTTP response status code class. E.g. "2xx", "4xx", "5xx".
-- `scheme`: Request scheme such as HTTP, gRPC, and gRPCs.
-- `path`: The HTTP path pattern. Only available if the attribute `include_path` is set to true.
-- `method`: The HTTP method. Only available if the attribute `include_method` is set to true.
+You can configure most options in the agent's main configuration file `datadog.yaml` through environment variables prefixed with `DD_`. For more information, see [agent environment variables](https://docs.datadoghq.com/agent/guide/environment-variables).
 
 :::note
 
-If there are no suitable values for any particular tag, the tag will be omitted.
+You can fetch the `admin_key` from `config.yaml` and save to an environment variable with the following command:
+
+```bash
+admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"//g')
+```
 
 :::
 
-## Enable Plugin
+### Update Datadog Agent Address and Metadata
 
-Once you have your Datadog agent running, you can enable the Plugin as shown below:
+By default, the Plugin expects the DogStatsD server to be available at `127.0.0.1:8125`. To customize the address and other metadata, update the Plugin metadata. Set the host to your Datadog agent address, the port to the agent listening port, the namespace to prefix all metrics, and add any constant tags:
 
 ```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d '
-{
-      "plugins": {
-            "datadog": {}
-       },
-      "upstream": {
-           "type": "roundrobin",
-           "nodes": {
-               "127.0.0.1:1980": 1
-           }
-      },
-      "uri": "/hello"
-}'
+curl "http://127.0.0.1:9180/apisix/admin/plugin_metadata/datadog" -X PUT \
+  -H "X-API-KEY: ${admin_key}" \
+  -d '{
+    "host": "192.168.0.90",
+    "port": 8125,
+    "namespace": "apisix",
+    "constant_tags": [
+      "source:apisix",
+      "service:custom"
+    ]
+  }'
 ```
 
-Now, requests to the endpoint `/hello` will generate metrics and push it to the DogStatsD server.
+To reset to default configuration, send a request to the `datadog` Plugin metadata with an empty body:
 
-## Delete Plugin
+```shell
+curl "http://127.0.0.1:9180/apisix/admin/plugin_metadata/datadog" -X PUT \
+  -H "X-API-KEY: ${admin_key}" \
+  -d '{}'
+```
+
+### Monitor Route Metrics
 
-To remove the `datadog` Plugin, you can delete the corresponding JSON configuration from the Plugin configuration. APISIX will automatically reload and you do not have to restart for this to take effect.
+The following example demonstrates how to send the metrics of a particular Route to Datadog.
+
+Create a Route with the `datadog` Plugin. Set `batch_max_size` to `1` to send each metric immediately, and `max_retry_count` to `0` to disallow retries if metrics were unsuccessfully sent:
 
 ```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d '
-{
-    "methods": ["GET"],
-    "uri": "/hello",
-    "plugins": {},
+curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
+  -H "X-API-KEY: ${admin_key}" \
+  -d '{
+    "id": "datadog-route",
+    "uri": "/anything",
+    "plugins": {
+      "datadog": {
+        "batch_max_size": 1,
+        "max_retry_count": 0
+      }
+    },
     "upstream": {
-        "type": "roundrobin",
-        "nodes": {
-            "127.0.0.1:1980": 1
-        }
+      "type": "roundrobin",
+      "nodes": {
+        "httpbin.org:80": 1
+      }
     }
-}'
+  }'
+```
+
+Generate a few requests to the Route:
+
+```shell
+curl "http://127.0.0.1:9080/anything"
 ```
+
+In Datadog, select **Metrics** from the left menu and go to **Explorer**. Select `apisix.ingress.size.count` as the metric. You should see the count reflecting the number of requests generated.
diff --git a/docs/en/latest/plugins/elasticsearch-logger.md b/docs/en/latest/plugins/elasticsearch-logger.md
@@ -125,7 +125,7 @@ curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
       "elasticsearch-logger": {
         "endpoint_addrs": ["http://elasticsearch:9200"],
         "field": {
-          "index": "gateway"
+          "index": "gateway",
         }
       }
     },
@@ -288,7 +288,7 @@ curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
       "elasticsearch-logger": {
         "endpoint_addrs": ["http://elasticsearch:9200"],
         "field": {
-          "index": "gateway"
+          "index": "gateway",
         },
         "include_req_body": true,
         "include_req_body_expr": [["arg_log_body", "==", "yes"]]