Menu

Important: This documentation is about an older version. It's relevant only to the release noted, many of the features and functions have been updated or replaced. Please view the current version.

Datadog query editor

Grafana provides a query editor for Datadog, which allows you to create and execute Datadog queries, get monitoring status, retrieve service-level objectives (SLOs), perform arithmetic, and alias the graph’s legend.

Datadog query editor options

The following are Datadog query types:

Query

Use the Query query type to get metrics. Use the visual query builder to construct your query.

  • Metric - Select a metric from the dropdown list.
  • From - Select an optional tag from the dropdown list.
  • Aggregate - Select an aggregation from the dropdown list. The default is average.
  • Group by - Click the + sign to select a group by option from the dropdown list. You can select multiple tags.
  • Functions - Click the + sign to select a function from the dropdown list. You can add multiple functions.
  • Alias by - Use plain text to add an alias to change titles and headings in a graph’s legend.
  • Alias RegExp - Use a regular expression to add an alias to change titles and headings in a graph’s legend.

For Alias By, use plain text, scoped variables listed as follows, or both.

Scoped variables for meticsReplaced with
$__metricmetric name
$__display_namemetric name
$__expressionfull metric expression
$__aggrmetric aggregation function (e.g. avg, max, min, sum)
$__scopemetric scope (e.g. region, site, env, host)
$__tag_namecorresponding tagName. Applicable only to group by queries. (e.g: when using group by host use $__tag_host as alias)
$__scope_namewhen 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
$__namename (same as what is selected in the Objective dropdown)
$__aggraggregation function (e.g. avg, max, min, sum)
$__metricmetric name
$__scopescope name
$__numeratormetric used as the numerator in the SLO calculation
$__denominatormetric used as the denominator in the SLO calculation

Raw query

A raw query is similar to a regular query, but there is no visual query builder. You create a query directly in the text box. You can also use Alias by and Alias RegExp like you would in a Query type query.

Arithmetic

Arithmetic type queries perform mathematical operations and are considered metrics queries.

  • Expression - Supported arithmetic operations include +, -, *, /, and ().

Note: arithmetic queries are only supported with other datadog metric queries.

Examples:

#A * 2 doubles the result of query A.

#A / #B divides the results of query A by query B.

Real User Monitoring

Real User monitoring queries, or RUM queries, allow you to query Datadog RUM events. For more information on RUM see What is Real User Monitoring? RUM queries return a maximum of 1000 recent events. Results are automatically filtered to a dashboard’s time range.

Note

RUM queries are currently in public preview.
  • Query mode - There are 2 RUM query modes, Search and Aggregate.

    • Search - RUM search queries return RUM events.

      • Query- Enter your query following RUM search syntax.
      • Sort - Select a sort parameter for querying. Click either Timestamp DESC or Timestamp ASC.
      • Limit - Set a maximum number of events returned. The default is 1000.
    • Aggregate - RUM aggregate queries return aggregated RUM events.

      • Query- Enter your query following RUM search syntax.
      • Compute - Compute an aggregate. Add an Aggregation from the dropdown menu, an optional Metric (or use * when selecting a count aggregation) and a Type, which can be either Total or Time Series.
      • Group by - Add a Facet and a Limit to your Group by. The limit default is 1000.
      • Limit - The Maximum number of events in the response. The default is 1000.
      • Display options - Add an alias to create a custom name for your results.

You can use the following aliases when using the RUM query type:

Scoped variables for meticsReplaced with
$__metric$__metric will replaced by metric name
$__label_xyzreplaced with the label xyz where xyz can be any valid label returned by DD. example: $__label_host
$__no_labelswhen your alias have $__no_labels, grafana won’t attach additional labels to the fields

Logs

Logs queries allow you to query Datadog logs. Results are filtered to a dashboard’s time range automatically.

  • Query mode - There are 2 Logs query modes, Search and Aggregate.

    • Search - Use log query syntax to search Datadog logs.

      • Search query - Enter you logs search query.
      • Sort by - Select either Timestamp DESC or Timestamp ASC to sort by timestamp and add an optional Limit to set a maximum number of logs in the response. The default is 1000.
    • Aggregate - Aggregate logs and/or events into buckets and compute metrics and timeseries.

      • Compute - Compute an aggregate. Add an Aggregation from the dropdown menu, an optional Metric (or use * when selecting a count aggregation) and a Type, which can be either Total or Time Series.
      • Group by - Add a Facet and a Limit to your Group by. The limit default is 1000.
      • Limit - The Maximum number of events in the response. The default is 1000.
      • Display options - Add an alias to create a custom name for your results.

Monitor

Alerts in Grafana are called monitors in Datadog. Monitor queries fetch and list data and status information regarding alerts. For more information regarding monitors see Monitor types. For more information about monitor queries, see Search Monitors.

  • Search type - Select from 2 monitor query search types, Individual or Group.

Note

The Group mode search type is in pubic preview.
  • Individual mode - Search and filter your monitor details.

    • Result type - Click the dropdown to select from the following list of results types:
      • Count by status - Display the monitor count by status.
      • Count by type - Display the monitor count by type.
      • Count by tags - Display the monitor count by tag.
      • Count by mute status - Display the monitor count by mute status.
      • Monitors list - List all of the monitors and their corresponding states and other related details. List options include sorting by Name, Status or Tags, ASC or DESC order and an Items per page limit.
    • Query- Optional. Add a Datadog monitor filter query. If you specify a filter query, the count or list will return only the monitors that match the query.
  • Group mode - Similar to an individual monitor search, you can also search and filter your monitor group details. See Monitors group search for underlying API details. This endpoint requires the monitors_read authorization scope.

    • Result type - Click the dropdown to select from the following list of results types:
      • Count by status - Display the monitor count by status.
      • Count by type - Display the monitor count by type.
      • Monitors list - List all of the monitors and their corresponding states and other related details. List options include sorting by Name, Status or Tags, ASC or DESC order and an Items per page limit.
    • Query- Optional. Add a Datadog monitor filter query. If you specify a filter query, the count or list will return only the monitors that match the query.

Examples:

  • status:(alert OR ok OR "no data" OR warn) lists the monitors with at least one of status alert, ok, no data, or warn.
  • status:(alert OR warn) type:metric "cassandra" lists the metric monitors with alert or warn status and also related to “cassandra”.
  • id:(7254197 OR 240232) displays only the status of monitors with ID 7254197 or 240232.

Note

For the Monitors list option, due to API limits only the top n monitors specified by the items per page setting are retrieved and displayed.

Events

Events queries allow you to query the Datadog event stream. For more information on events see Event Management. Events queries return a maximum of 1000 of the most recent results. Results are also automatically filtered to the dashboard’s time range.

Note

The Events query type is in pubic preview.

Filter your results by the following:

  • Sources - Enter a list of sources to filter in the query.

  • Tags - Enter the tags to filter in the query.

  • Priority - Select the priority of events. Options are All, Low or Normal.

Service Level Objective

Get SLOs, or service level objectives, by setting the Query type to SLO. SLOs are populated from your Datadog account. For more information see Service Level objectives and Get an SLO’s history.

For monitor type SLO queries, you can optionally expand individual monitor results.

Note

The SLO Value result type is in public preview.
  • Result type - Select a result type, either Timeseries or Value.

    • Timeseries -

    • Value - Displays only the current SLO value.

  • Objective - Select an objective from the dropdown list.

  • Alias by - Available only with the Timeseries result type. Use plain text to add an alias to change titles and headings in a graph’s legend.

  • Alias RegExp - Available only with the Timeseries result type. Use a regular expression to add an alias to change titles and headings in a graph’s legend.

Error messages

When the underlying Datadog API returns non successful status codes, the plugin will throw the error with a corresponding status code. If you are seeing error message such as 429 Too Many Requests, that indicates you may be hitting Datadog API rate limits.

For more information regarding rate limits see Rate Limits in Datadog’s documentation.