Forward Analytics Data to Datadog


Follow the steps in this guide to set up an NGINX Controller Integration that forwards data to Datadog.

Before You Begin

This guide assumes that you are already an active Datadog user. If you haven’t already done so, you will need to install and configure Datadog before you proceed.

Generate a Datadog API Token

NGINX Controller sends data to the Datadog API; NGINX Controller does not use an agent. Datadog requires that NGINX Controller present an access token with the data to authenticate the service.

  1. Log into the Datadog web interface.
  2. On the navigation menu, select Integrations > APIs.
  3. Expand the API Keys pane.
  4. If you already have a key available, you can use it. If you don’t, or if you want to create a different key, you can do so by typing a key name and clicking Create API key.
  5. Copy and save the API key you want to use. You’ll configure NGINX Controller with this value later.
Datadog restricts the creation of API keys to Admin users. You may need to contact your administrator to get a new key.

Create an Integration

Take the following steps to create an Integration for Datadog:

  1. Open the NGINX Controller user interface and log in.
  2. Select the NGINX Controller menu icon, then select Platform.
  3. On the Platform menu, select Integrations.
  4. On the Integrations menu, select the Create Integration quick action.
  5. Add a name.
  6. (Optional) Add a display name.
  7. (Optional) Add a description.
  8. (Optional) Add tags.
  9. In the Integration Type list, select GENERIC_INTEGRATION.
  10. In the Endpoint URI box, add the API endpoint for your Datadog region. For example, for metrics or for events.
  11. In the Credential Type list, select API_KEY.
  12. In the API Key box, add the Datadog API Key.
  13. Select Submit.

Create a Forwarder

Use the NGINX Controller REST API to create a Forwarder.

To create a Forwarder, send a POST request to the analytics/forwarders endpoint with a request similar to the following example.

You must reference the Integration in the JSON request body. Requests that do not contain a valid Integration reference will return an error message.


  "metadata": {
    "name": "datadog-forwarder",
    "displayName": "Datadog - Metrics",
    "description": "Metrics forwarder for Datadog"
  "desiredState": {
    "collectorType": "DATADOG",
    "integrationRef": {
      "ref": "/platform/integrations/<name-of-datadog-integration>"
  "streams": [
        "inputDataType": "METRICS",
        "outputFormat": "DATADOG",
        "selector": "names=http.request.count, IN ('GET', 'POST')"



  • name: The resource name to use for the Forwarder.
  • displayName (Optional): The friendly name to show for the Forwarder.
  • description (Optional): A brief description of the Forwarder.


  • integrationRef.ref: The Integration reference for the Forwarder. Use the format /platform/integrations/<name-of-datadog-integration>. Use the name for the Integration that you created in the Create an Integration procedure.
  • collectorType: The type of collector. For Datadog collector use, DATADOG.


  • inputDataType: The type of data to forward. NGINX Controller can forward METRICS or EVENTS data to Datadog.

  • outputFormat: The format for the output. For Datadog-formatted output, use DATADOG. +- selector: Consists of the following query parameters (optional):

    • names (inapplicable for EVENTS): The list of metrics names that you want to forward.
    • excluded_names (inapplicable for EVENTS): The list of metric names that you don’t want to forward.
    • filter: The conditions to use to refine the metrics or events data.
    • Example usage when selecting metrics: "names=nginx.*&excluded_names=nginx.upstream.*filter=app='myapp'"
    • Example usage when selecting events: "filter=type='security violation' AND app='my-app'"

Each metric will be prefixed with a common namespace – such as “nginx-controller” – before it is sent to Datadog. This prefix is used by Datadog only and is not applied to any of the internal NGINX Controller metrics. Refer to the metrics catalog for the full list of valid metric names.

For events, the “nginx-controller” namespace is added to the “ddsource” key.

NGINX Controller events are sent to Datadog as logs and NGINX Controller dimensions are sent as tags. The Forwarder converts the dimension data to comply with the Datadog tags format prior to forwarding it. In some cases, the original dimension value may be transformed to fit the tag requirements. This includes replacing comma characters (,) with semicolons (;) to ensure that Datadog will properly handle the incoming payload.

See Also:
See the NGINX Controller Metrics docs for more information.


Soon after you create the Datadog forwarder, you can view the selected metrics in Datadog.

  1. Log into the Datadog web interface.
  2. On the navigation menu, select Metrics > Summary.

What’s Next

This documentation applies to the following versions of NGINX Controller Documentation: 3.8, 3.9, 3.10, 3.11, 3.12, 3.13, 3.14, 3.15 and 3.16.