Datadog data source for Grafana
The Datadog data source for Grafana allows you to query and visualize Datadog metrics from within Grafana. With our hosted Datadog metrics service, you can also forward metrics directly from your Datadog agents.
Requirements
This plugin has the following requirements:
- A Datadog account
- One of the following account types:
- Available for users with a Grafana Cloud Free, Advanced or Trial account or with an activated Grafana Enterprise license.
Install the data source plugin
To install the data source, refer to Installation.
Compatibility requirements
For this plugin, there are no compatibility requirements.
Verify that the plugin is installed
- In Grafana Enterprise from the left-hand menu, navigate to Configuration > Data sources.
- From the top-right corner, click the Add data source button.
- Search for
Datadog
in the search field, and hover over the Datadog search result. - Click the Select button for Datadog.
- If you can click the Select button, then it is installed.
- If the button is missing or disabled, then the plugin is not installed. Check to see if your Grafana Enterprise license is valid, and reinstall the plugin. If you still need help, contact Grafana Labs.
Note: On Grafana Cloud, it can take up to 15 minutes to see the data source plugin within Grafana.
Choose if you want to host the Datadog metrics in Grafana Cloud
The Datadog data source plugin can work by being connected to Datadog (using an API key) or by sending the metrics from the Datadog agents. By being connected to Datadog using an API key, you are only hosting the metrics in Datadog but can face API rate limits. Using our hosted Datadog Metrics service solves this issue by storing data in Grafana Cloud.
The section below describes how to connect Datadog to Grafana. The page dedicated to hosted Datadog Metrics describes how to send data from your Datadog agents to Grafana.
Configuration
Get an API key and application key from Datadog
- Login to the https://datadoghq.com and create api key and app key using following steps.
- Create an API key
- Navigate to Organization settings in the datadog app page, then click the API keys tab.
- Click New key and enter a unique key name.
- Click Create key
- Copy the API Key you just created
- Create an Application key
- Navigate to Organization settings in the datadog app page, then click the Application keys tab.
- Click New key and enter a unique key name.
- Click Create key
- Copy the Application Key you just created
Configure the data source
To add a new Datadog data source, refer to Add a data source, and fill in the following fields:
Datadog settings
Field | Description |
---|---|
Name | A name for this particular Datadog data source. |
Mode | Choose default to directly connect to DataDog API endpoints. Choose Hosted Datadog Metrics, if you want to connect using a Datadog proxy through Hosted Datadog Metrics. |
API URL / Region | URL to the Datadog API. For example, https://api.datadoghq.com or https://api.datadoghq.eu . |
API Key | API key from Datadog. |
APP Key | Application key from Datadog. |
Show API rate limits | Show Datadog API limits for each queried endpoint. To view the API rate limits, go to the Query Inspector > JSON tab, and set Select source to DataFrame structure |
Enable API rate limit threshold | Enable rate limit. Datadog query will stop once it reaches entered threshold. |
API rate limit threshold % | Enter percentage of threshold. (If the API hit the % of rate limit, plugin will block subsequent requests till next reset) |
Disable Data links | Check this to disable data links. Data links are the links that takes user to the datadog app when they interact with panels |
Enable Basic Auth | Use Basic authentication when calling the API URL. This is useful when using a proxy. |
Configure the data source with provisioning
Configure the Datadog data source using configuration files with Grafana’s provisioning system. To learn more about how the provisioning system works, including all of the data source settings, refer to Provisioning Grafana.
Here is a provisioning example for this data source:
apiVersion: 1
datasources:
- name: DATADOG
type: grafana-datadog-datasource
jsonData:
url: https://api.datadoghq.com
logApiRateLimits: false
rateLimitEnabled: false
rateLimitMetrics: 100
disableDataLinks: false
secureJsonData:
apiKey: API Key
appKey: Application Key
Query the data source
The query editor allows you to query Datadog, get monitor status, get service-level objectives (SLOs), perform arithmetic, and alias the graph’s legend.
Query
Get metric queries by setting QueryType to Query
.
- Select the metric or click the query edit button to type your metric
- Select the aggregation type (default is average)
- Optionally select one or more tags if you want to filter results with
From
andGroup By
- Optionally select the functions dropdown to select a Datadog function. These can be reordered and removed by clicking on them and clicking the arrows or x
Aliasing the legend
You can use Alias By
and Alias RegExp
to change the text in the graph’s legend. For Alias By
, use plain text, scoped variables listed as follows, or both.
Scoped variables for metics | Replaced with |
---|---|
$__metric | metric name |
$__display_name | metric name |
$__expression | full metric expression |
$__aggr | metric aggregation function (e.g. avg, max, min, sum) |
$__scope | metric scope (e.g. region, site, env, host) |
$__tag_name | corresponding tagName. Applicable only to group by queries. (e.g: when using group by host use $__tag_host as alias) |
$__scope_name | when there are multiple scope items available, use this alias to extract the specific scope name. (e.g: to extract host scope, use $__scope_host as alias) |
Scoped variables for (SLOs) | Replaced with |
---|---|
$__name | name (same as what is selected in the Objective dropdown) |
$__aggr | aggregation function (e.g. avg , max , min , sum ) |
$__metric | metric name |
$__scope | scope name |
$__numerator | metric used as the numerator in the SLO calculation |
$__denominator | metric used as the denominator in the SLO calculation |
To use regular-expression aliasing, fill out Alias RegExp
with a regular expressions to find matches that are separated by commas.
Arithmetic
Use metric arithmetic by setting Query type to Arithmetic
.
- To perform an arithmetic operation, there must be at least one other query in the query editor.
- The supported arithmetic operations are
+
,-
,*
,/
, and()
. - To refer to a metric, use
#
followed by the query’s name. For example,#A
.
Note: arithmetic queries are only supported with other datadog metric queries.
Arithmetic example
#A * 2
doubles the result of query A.
#A / #B
divides the results of query A by query B.
Monitor
Display the monitors list and status information by setting Query type to Monitor
. Alerts in Grafana are referred to as monitors in Datadog. For more information, refer to Monitors.
The following options are available:
- Count by status, type, tags, or mute status
- Monitors list
Count by: Display the count of monitors by status, type, tag, or mute status.
Monitors list: List all of the monitors and their corresponding states and other related details.
Query: For the Count by
and Monitors list
options, you can optionally specify the filter query. If you specify the filter query, the count or list will return only the monitors that match the query.
For more information about monitor queries, refer to QUERY.
Example queries:
status:(alert OR ok OR "no data" OR warn)
lists the monitors with at least one of statusalert
,ok
,no data
, orwarn
.status:(alert OR warn) type:metric "cassandra"
lists the metric monitors withalert
orwarn
status and also related to “cassandra”.id:(7254197 OR 240232)
displays only the status of monitors with ID7254197
or240232
.
Note: For the Monitors list option, and due to API limits, only the top n monitors specified by the
items per page
setting are retrieved and displayed.
All the monitor queries will have data links to the datadog application. To disable the data links, check Disable Data links
option in the config.
Monitor Group Search
Similar to a monitor search, you can also search and filter your monitor group details. Underlying API details can be found here. This endpoint requires the monitors_read authorization scope.
Events
Events query allow you to query the datadog event stream.
- This query returns a maximum of 1000 most recent result
- Results will be filtered to dashboard’s time range automatically
- Optionally, you can filter the results by sources, tags and priority
Real User Monitoring / RUM
RUM query allow you to query the datadog RUM events
- This query returns a maximum of 100 recent events
- Results will be filtered to dashboard’s time range automatically
You can also use the following alias when using RUM query type
Scoped variables for metics | Replaced with |
---|---|
$__metric | $__metric will replaced by metric name |
$__label_xyz | replaced with the label xyz where xyz can be any valid label returned by DD. example: $__label_host |
$__no_labels | when your alias have $__no_labels , grafana won’t attach additional labels to the fields |
Logs Search
Logs query allow you to query the datadog logs
- This query returns a maximum of 100 recent logs
- Results will be filtered to dashboard’s time range automatically
Logs analytics / aggregation
Logs aggregation query type helps you to aggregate logs/events into buckets and compute metrics and timeseries.
Service-level objectives (SLOs)
Get SLOs by setting Query type to SLO
. Select an objective from the list. The SLOs are populated from your Datadog account.
With the result type option, you can choose one of timeseries
/value
. With the value
option selected, only the current SLI value will be displayed. For monitor type SLO queries, you can optionally expand individual monitor results.
Note You can find the underlying API documentation in the datadog docs. Also note that the underlying API is in beta.
Error messages
When the underlying DataDog API returns non successful status codes, the plugin will throw the error with corresponding status code.
If you are seeing error message such as 429 Too Many Requests
, that potentially indicates that you are hitting the DataDog API rate limits. You can learn more about the DataDog rate limits here.
Templates and variables
To add a new Datadog query variable, refer to Add a query variable. Use your Datadog data source as your data source. The following queries are available:
Query | Description |
---|---|
* | Fetches the list of available metrics |
tag | Returns all tag tags using the value tag |
scope | Returns all scope tags using the value scope |
host | Returns all host tags |
device | Returns all device tags |
env | Returns all env tags |
region | Returns all region tags |
site | Returns all site tags |
status | Returns all status tags |
version | Returns all version tags |
For custom tag groups, enter the tag group name. For example, if your custom tag group name is subscription_name
, then enter that in the Query field.
After you create a variable, you can it in your Datadog queries. For more information, refer to Variable syntax.
For more information about variables, refer Templates and variables.
Import a dashboard for Datadog
To import a dashboard, refer to Import a dashboard.
To find your imported dashboards, go to Configuration > Data sources.
To see the available pre-made dashboards, select the Datadog data source, and select the Dashboards tab.
Ad-hoc filters
Grafana Enterprise type of template variable called Ad-hoc filters, which applies to all the Datadog queries in a dashboard. This filter acts as sa quick filter. An ad-hoc variable for Datadog fetches all the key-value pairs from tags, such as region:east
or region:west
, and uses them as query tags. To create this variable, select the Ad-hoc filters type and choose your Datadog data source. You can name this variable anything.
Note: ad-hoc filters are only supported with metric query type
Learn more
- Add Annotations.
- Configure and use Templates and variables.
- Add Transformations.
- Set up alerting; refer to Alerts overview.
Related resources from Grafana Labs


