# Datadog data source for Grafana

The Datadog data source for Grafana allows you to query and visualize Datadog metrics from within Grafana.

## Requirements

The Datadog data source has the following requirements:
* Grafana Enterprise with a valid license. Refer to [Activate an Enterprise license](https://grafana.com/docs/grafana/latest/enterprise/activate-license/).
* Grafana user with a server or organization administrator role. Refer to [Permissions](https://grafana.com/docs/grafana/latest/permissions/).
* An active Datadog account. <!-- ???: figure out which permissions are required in Datadog -->

## Known limitations

* Although this data source supports metrics from Datadog, it does not support logs, traces, or monitors from Datadog.

## Install the data source plugin

To install the data source, refer to [Installation](https://grafana.com/grafana/plugins/grafana-datadog-datasource/?tab=installation).

### Conform to compatibility requirements

For this plugin, there are no compatibility requirements.

### Verify that the plugin is installed

1. In Grafana Enterprise from the left-hand menu, navigate to **Configuration** > **Data sources**.
2. From the top-right corner, click the **Add data source** button.
3. Search for `Datadog` in the search field, and hover over the Datadog search result.
5. 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](https://grafana.com/contact).

> **Note:** On Grafana Cloud, it can take up to 15 minutes to see the data source plugin within Grafana.

## Get an API key and application key from Datadog

The following procedure assumes you have installed the Datadog plugin.

1. Go to [https://datadoghq.com](https://datadoghq.com).
2. Set up an API key and copy your application key.
3. Add the API key to the Datadog plugin:
a. Navigate to [Integration -> APIs](https://app.datadoghq.com/account/settings#api), enter a unique key name, and click `Create API key`.

Get your Application Key by navigate to [Teams -> Application Key](https://app.datadoghq.com/access/application-keys) and copying the desired `KEY ID`.

### Configure the data source

To add a new Datadog data source, refer to [Add a data source](https://grafana.com/docs/grafana/latest/datasources/add-a-data-source/), and fill in the following fields:

#### Datadog settings

| Field | Description |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Name | A name for this particular Datadog data source. |
| API URL | URL to the Datadog API. For example, `https://api.datadoghq.com`. |
| API Key | [API key from Datadog](#get-api-key-and-application-key-from-datadog). |
| APP Key | [Application key from Datadog](#get-api-key-and-application-key-from-datadog). |
| Cache Interval | Caching is used to limit the number of API calls. The default cache period is 60 seconds. |
| Cache Size | Caching is used to limit the size of API calls. The default cache size is 100 MB. |
| Show API rate limits | Show Datadog API limits for each queried endpoint. To view the API rate limits, go to the **JSON** tab > **Query Inspector**, and set **Select source** to `DataFrame structure` |
| Enable Basic Auth | Use Basic authentication when calling the API URL. This is useful when using a proxy. |

### Configure the data source with provisioning

It is possible to configure data sources using configuration files with Grafana’s provisioning system. To understand how the provisioning system works, including all of the data source settings, refer to [Povisioning Grafana](https://grafana.com/docs/grafana/latest/administration/provisioning/#datasources).

Here is a provisioning example for this data source:

apiVersion: 1

datasources:
  - name: DATADOG
    type: grafana-datadog-datasource
    access: proxy
    basicAuth: false
    jsonData:
      url: https://api.datadoghq.com
      api_key: API Key
      app_key: Application Key
      cacheInterval: 60
      cacheSize: 100
      logApiRateLimits: false

## Query the data source

The query editor allows you to query Datadog, get service-level objectives (SLOs), perform arithmetic, and alias the graph’s legend.

### Query

Get metric queries by setting Query type to `Arithmetic`.

* 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` and `Group 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

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

#### 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`.

##### Expression example

`#A * 2` doubles the result of query *A*.

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

### 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) |

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

### Templates and variables

To add a new Datadog query variable, refer to [Add a query variable](https://grafana.com/docs/grafana/latest/variables/variable-types/add-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](https://grafana.com/docs/grafana/latest/variables/syntax/).

For more information about variables, refer [Templates and variables](https://grafana.com/docs/grafana/latest/variables/).

## Get the most out of the plugin

<!-- ??? --->

### Import a dashboard for Datadog

To import a dashboard, refer to [Import a dashboard](https://grafana.com/docs/grafana/latest/dashboards/export-import/#importing-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.

## Learn more

* Add [Annotations](https://grafana.com/docs/grafana/latest/dashboards/annotations/).
* Configure and use [Templates and variables](https://grafana.com/docs/grafana/latest/variables/).
* Add [Transformations](https://grafana.com/docs/grafana/latest/panels/transformations/).
* Set up alerting; refer to [Alerts overview](https://grafana.com/docs/grafana/latest/alerting/).