Documentation Plugins Datadog data source Configure

Configure the Datadog data source

Grafana provides a number of configuration options for Datadog. To install the Datadog plugin, refer to Install the Datadog data source plugin. For general information about adding a data source, refer to Add a data source.

Before you begin

Before you configure the Datadog data source, ensure you have:

• A Grafana Cloud Pro or Advanced plan, or a self-managed Grafana Enterprise license that includes this plugin. The Datadog data source is an Enterprise plugin. Without the required license or entitlement, the plugin doesn’t install or enable, and you might not see an Install or Enable button on the plugin page. Free and Starter plans don’t include Enterprise plugins. For details, refer to Grafana Cloud features.
• Grafana version 11.6.11 or later.
• The organization administrator role, which you need to add data sources. Administrators can also configure the data source with the Grafana provisioning system.
• A Datadog API key and application key. For instructions, refer to Get an API key and application key from Datadog.

Key concepts

If you’re new to Datadog, these terms appear throughout the configuration:

Configure the data source

To add the Datadog data source, complete the following steps:

1. Install the Datadog plugin.
2. Click Connections in the left-side menu.
3. Under Connections, click Add new connection.
4. Enter Datadog in the search bar.
5. Select Datadog under the Data Source section.
6. Click Add new data source in the upper right.

Grafana opens the Settings tab, where you set up your Datadog configuration.

Configuration options

The following is a list of configuration options for Datadog.

The first option to configure is the name of your connection:

• Name - The data source name. This is how you refer to the data source in panels and queries. Examples: Datadog_Metrics, Datadog-1.

• Default - Toggle to set as the default data source when creating queries.

Connection

You can connect to Datadog using two connection modes, Default or Hosted Datadog Metrics.

• Mode - Select your connection mode for Datadog.

  • Default - Connect directly to Datadog API endpoints.

  • Hosted Datadog Metrics - Deprecated. This mode remains available for Grafana Cloud Datadog proxy users. For more information, refer to Send or visualize Datadog metrics. To forward Datadog agent metrics into Grafana Cloud, refer to Receive traces and metrics from Datadog-instrumented applications.

• API URL / Region - Default mode. Select your Datadog region from the list, or enter a custom API URL. The following regions are available:

  Expand table

  Region	API URL
  US1 / Default	https://api.datadoghq.com
  US3	https://api.us3.datadoghq.com
  US5	https://api.us5.datadoghq.com
  EU	https://api.datadoghq.eu
  US1-FED	https://api.ddog-gov.com

  The API URL / Region field also accepts a custom API URL. Use a custom URL for Datadog sites that aren’t in the list, such as AP1 (https://api.ap1.datadoghq.com).

• Hosted metrics URL - Hosted Datadog Metrics mode. The Grafana Cloud Datadog metrics endpoint, for example https://dd-prod-10-prod-us-central-0.grafana.net/datadog.

Authentication

The way you authenticate depends on your connection mode. Grafana shows Datadog authentication in Default mode and basic authentication in Hosted Datadog Metrics mode. The Authentication section also includes Grafana TLS settings.

If you connect using Default mode, configure the following:

• API key - Enter the Datadog API key unique to your organization. To generate an API key, refer to Add an API key or client token. For more information about API keys, refer to API and Application Keys in the Datadog documentation.

• App key - Enter the Datadog application key unique to your organization. The application key works in conjunction with the API key to grant user access. To generate an application key, refer to Add application keys. For more information about application keys, refer to Application keys in the Datadog documentation.

If you connect using Hosted Datadog Metrics, configure the following:

• Username - Your Grafana Cloud Prometheus username, from the Prometheus details in your Grafana Cloud portal.

• Password - A Grafana Cloud API key or access policy token with metrics read permission.

API key and application key permissions

The Datadog data source authenticates each request with both keys:

• The API key identifies your Datadog organization. Every request requires it.
• The application key authorizes the request. By default, an application key inherits the permissions of the user who created it. You can also create a scoped application key that grants only specific permissions.

The application key must have permission to read the Datadog products that you query. Metric, time series, host, and tag queries don’t require a specific permission beyond valid keys. Other query types require the following Datadog permissions:

The Datadog Read Only role includes all of these permissions. The simplest setup is to create the application key under a user or service account that has at least the Read Only role. To follow the principle of least privilege, create a scoped application key with only the permissions for the query types that you use. For the full list of permissions, refer to Datadog Role Permissions.

Validate your keys

Before you enter your keys into Grafana, you can validate them against the Datadog API. Replace <api_key> and <app_key> with your keys, and use the API URL for your region.

Validate the API key:

Bash Copy

curl -X GET "https://api.datadoghq.com/api/v1/validate" \
  -H "DD-API-KEY: <api_key>"

A valid API key returns {"valid":true}.

Validate both keys together, and confirm that the application key can read metrics:

Bash Copy

curl -X GET "https://api.datadoghq.com/api/v1/metrics?from=$(($(date +%s) - 3600))" \
  -H "DD-API-KEY: <api_key>" \
  -H "DD-APPLICATION-KEY: <app_key>"

A 403 Forbidden response means that one or both keys are incorrect or lack the required permissions. To test a specific query type, call its endpoint from the preceding table. For example, to confirm the monitors_read permission, call /api/v1/monitor/search.

Additional settings

Additional settings is a collapsible section. Expand it to configure optional settings for more control over your Datadog data source.

• API rate limits

  • Show API rate limits - Check the box to show Datadog API limits for each queried endpoint. To view the API rate limits, go to the Query Inspector, select JSON, and set select source to DataFrame structure.

  • Enable API rate limit threshold - Check the box to enable rate limiting. Datadog queries stop once the threshold is reached.

  • API rate limit threshold % - Appears when you enable the threshold. Enter a threshold percentage. When the API hits the rate limit percent specified, the plugin blocks subsequent requests until the next reset. The default is 100. The maximum is 100.

• Data links

  • Disable data links - Check the box to disable data links. The Datadog data source adds data links to Monitor query results, which let users open the relevant monitor directly in Datadog. For more information, refer to Data links.

• Size

  • Response Size - Set the maximum number of items to retrieve in a single API request, such as the metric list, host list, or tags for a metric. The default is 100. This setting doesn’t limit all-tags template variables, which use a Datadog API maximum of 1000.

• PDC Connect

  • Secure Socks Proxy - Available when the secureSocksDSProxyEnabled feature toggle is enabled. Route the data source connection through the Secure Socks Proxy to a different network. For setup instructions, refer to Connect through the Secure Socks Proxy.

After you configure your Datadog data source options, click Save & test at the bottom to test your data source connection. When the connection succeeds, Grafana displays an OK message. You can also remove a connection by clicking Delete.

Connect through the Secure Socks Proxy

By default, Grafana connects directly to the Datadog API over the public internet. If your network policy requires outbound traffic to route through a specific network, you can send the data source connection through the Secure Socks Proxy. The Secure Socks Proxy toggle, in the PDC Connect section of Additional settings, appears only when the secureSocksDSProxyEnabled feature toggle is enabled.

Grafana Cloud

In Grafana Cloud, use Private data source connect (PDC) to route the connection through a network that you control:

1. Set up a PDC network and run the PDC agent. For instructions, refer to Configure Private data source connect.
2. In the Datadog data source configuration, enable the Secure Socks Proxy toggle in the PDC Connect section.
3. Select your PDC network and click Save & test.

Self-managed Grafana

1. Enable the secureSocksDSProxyEnabled feature toggle.
2. Configure the secure socks proxy in the [secure_socks_datasource_proxy] section of grafana.ini. For instructions, refer to Configure a data source connection proxy.
3. In the Datadog data source configuration, enable the Secure Socks Proxy toggle and click Save & test.

Configure the data source with provisioning

Configure the Datadog data source using configuration files with the Grafana provisioning system. To learn more about how the provisioning system works, including all of the data source settings, refer to Provisioning Grafana.

You can define and configure the Datadog data source in YAML files as part of the Grafana provisioning system. For more information about provisioning a data source, and for available configuration options, refer to Provision Grafana.

The following example is for provisioning the Datadog data source:

YAML Copy

apiVersion: 1
datasources:
  - name: Datadog
    type: grafana-datadog-datasource
    jsonData:
      pluginMode: default
      url: https://api.datadoghq.com
      logApiRateLimits: false
      rateLimitEnabled: false
      rateLimitMetrics: 100
      disableDataLinks: false
      size: 100
    secureJsonData:
      apiKey: <YOUR_DATADOG_API_KEY>
      appKey: <YOUR_DATADOG_APPLICATION_KEY>

The following table describes the available jsonData and secureJsonData fields:

For Hosted Datadog Metrics, set pluginMode to hosted-metrics, enable basic authentication on the data source, and store the Grafana Cloud token in secureJsonData.basicAuthPassword:

YAML Copy

apiVersion: 1
datasources:
  - name: Datadog hosted metrics
    type: grafana-datadog-datasource
    basicAuth: true
    basicAuthUser: <YOUR_GRAFANA_CLOUD_PROMETHEUS_USERNAME>
    jsonData:
      pluginMode: hosted-metrics
      url: https://dd-prod-10-prod-us-central-0.grafana.net/datadog
    secureJsonData:
      basicAuthPassword: <YOUR_GRAFANA_CLOUD_ACCESS_POLICY_TOKEN>

Configure Datadog with Terraform

You can configure the Datadog data source as code using the Grafana Terraform provider. This approach enables version-controlled, reproducible data source configurations across environments.

The following example provisions a Datadog data source and defines the required variables:

Terraform Copy

terraform {
  required_providers {
    grafana = {
      source  = "grafana/grafana"
      version = "~> 3.0"
    }
  }
}

provider "grafana" {
  url  = var.grafana_url
  auth = var.grafana_auth
}

resource "grafana_data_source" "datadog" {
  type = "grafana-datadog-datasource"
  name = "Datadog"

  json_data_encoded = jsonencode({
    pluginMode        = "default"
    url               = var.datadog_api_url
    logApiRateLimits  = false
    rateLimitEnabled  = false
    rateLimitMetrics  = 100
    disableDataLinks  = false
    size              = 100
  })

  secure_json_data_encoded = jsonencode({
    apiKey = var.datadog_api_key
    appKey = var.datadog_app_key
  })
}

# Variables
variable "grafana_url" {
  description = "Grafana instance URL"
  type        = string
  default     = "http://localhost:3000"
}

variable "grafana_auth" {
  description = "Grafana authentication, such as admin:password or a service account token"
  type        = string
  sensitive   = true
}

variable "datadog_api_url" {
  description = "Datadog API URL for your region"
  type        = string
  default     = "https://api.datadoghq.com"
}

variable "datadog_api_key" {
  description = "Datadog API key unique to your organization"
  type        = string
  sensitive   = true
}

variable "datadog_app_key" {
  description = "Datadog application key unique to your organization"
  type        = string
  sensitive   = true
}