Skip to main content
API7.ai Logo
Version: 3.19.0

Monitor APISIX Metrics with Datadog

Monitoring gateway traffic helps operators identify changes in request volume, latency, and payload size that can affect API reliability. Sending these metrics to Datadog makes APISIX activity available for dashboards, monitors, and operational analysis alongside other application and infrastructure telemetry.

The datadog plugin sends APISIX request, latency, and traffic-size metrics to a DogStatsD agent over UDP. The agent then forwards the metrics to Datadog.

In this example, the DogStatsD agent runs in the APISIX quickstart network. APISIX addresses the agent by container name, and the resulting route metrics are verified in Datadog.


APISIX sends metrics to a DogStatsD agent, which forwards them to Datadog

Prerequisite(s)​

  • Install Docker.
  • Install cURL to send test requests.
  • Follow the Getting Started tutorial to start APISIX in Docker. The commands below use the apisix-quickstart-net network created by that tutorial.
  • Create a Datadog account and obtain an API key.
  • If Admin API authentication is enabled, export an admin-role key as ADMIN_API_KEY. The Docker quickstart disables authentication for local evaluation; keep it enabled in production.

Start a DogStatsD Agent​

Export your Datadog API key, then set the Datadog site and the hostname that identifies this example:

export DD_API_KEY=replace-with-datadog-api-key
export DD_SITE=datadoghq.com
export DD_HOSTNAME=apisix-quickstart

Start DogStatsD in the APISIX quickstart network:

docker rm -f quickstart-dogstatsd 2>/dev/null || true

docker run -d --rm \
  --name quickstart-dogstatsd \
  --network apisix-quickstart-net \
  -e DD_API_KEY \
  -e DD_SITE \
  -e DD_HOSTNAME \
  -e DD_DOGSTATSD_NON_LOCAL_TRAFFIC=true \
  datadog/dogstatsd:7.81.2@sha256:475f87872f2847e1fe4e60370ad0b3a075726aa5b81f5f507f90ce53cecc7f6d

DD_DOGSTATSD_NON_LOCAL_TRAFFIC allows the agent to receive metrics from the APISIX container. Because APISIX and DogStatsD share apisix-quickstart-net, APISIX can send metrics to the agent by container name. You do not need a host-specific IP address or published UDP port.

Configure the DogStatsD Endpoint​

The plugin sends metrics to 127.0.0.1:8125 by default. Configure plugin metadata to use the DogStatsD container instead:

curl "http://127.0.0.1:9180/apisix/admin/plugin_metadata/datadog" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "host": "quickstart-dogstatsd",
    "port": 8125,
    "namespace": "apisix"
  }'

Configure Metric Collection​

Enable datadog globally, then create a sample route for monitored traffic:

Create a global rule that enables the plugin:

curl "http://127.0.0.1:9180/apisix/admin/global_rules/datadog" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "plugins": {
      "datadog": {}
    }
  }'

Create the sample route:

curl "http://127.0.0.1:9180/apisix/admin/routes/dd-route" -X PUT \
  -H "X-API-KEY: ${ADMIN_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "uri": "/anything",
    "upstream": {
      "type": "roundrobin",
      "scheme": "https",
      "pass_host": "node",
      "nodes": {
        "httpbin.org:443": 1
      }
    }
  }'

Verify Metrics​

Send several requests through the route to produce metric data:

for _ in 1 2 3; do
  curl -sS "http://127.0.0.1:9080/anything" > /dev/null
done

The plugin submits metrics in batches, so they might not appear immediately. In Datadog, open Metrics → Explorer and search for metrics under the apisix namespace, including:

  • apisix.request.counter
  • apisix.request.latency
  • apisix.upstream.latency
  • apisix.apisix.latency
  • apisix.ingress.size
  • apisix.egress.size

Use these metrics to build monitors and dashboards. See the datadog Plugin Hub reference for metric tags, batching options, and additional configuration.