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 Enterprise license, or a Grafana Cloud account with Enterprise plugins enabled. 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. On Grafana Cloud, Enterprise plugins are included on some plans and available as a paid add-on on others. 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.

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 2 different connection modes, Default or Hosted Datadog Metrics.

• Mode - Select your connection mode for Datadog.

  • Default - Connect directly to Datadog API endpoints.

  • Hosted Datadog Metrics - This mode is now deprecated. Refer to Datadog proxy documentation for more information.

• API URL / Region - Use with 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

Authentication

The way you authenticate depends on your connection method.

If you connect using Default mode, configure the following to authenticate:

• 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.

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, event, 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 are optional settings that you can configure for more control over your Datadog data source.

• API rate limits - Limit access to the Datadog API.

  • 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 the JSON option, and set the 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 % - Enter a threshold percentage in the box. When the API hits the rate limit percent specified, the plugin blocks subsequent requests until the next reset. The default is 100.

• 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.

• Response Size - Set the maximum number of items to retrieve in a single API request, such as when querying the metric list or host list. The default is 100.

• Secure Socks Proxy - Available when the secureSocksDSProxyEnabled feature toggle is enabled and you run Grafana version 10.0.0 or later. 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 the data source configuration, appears only when the secureSocksDSProxyEnabled feature toggle is enabled and you run Grafana version 10.0.0 or later.

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:
      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:

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({
    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
}