Request JSON Schema

Request JSON Schema

The general format for the REQUEST_SCHEMA is an array of one or more requests:


   "requests": [
        {
            "formulas": [
                {
                    "formula": "per_hour(query)"
                },
                {
                    "formula": "query1"
                },
                {
                    "formula": "query1 / 100"
                }
            ],
            "queries": [
                {
                    "data_source": "metrics",
                    "name": "query",
                    "query": "avg:system.load.5{*}"
                },
                {
                    "data_source": "logs",
                    "name": "query1",
                    "search": {
                        "query": "status:error"
                    },
                    "indexes": [
                        "*"
                    ],
                    "compute": {
                        "aggregation": "count"
                    },
                    "group_by": []
                }
            ]

Functions

You can apply functions to the result of each query.

For more information about functions explained through a series of examples, see the Examples page.

Aggregation method

In most cases, the number of data points available outnumbers the maximum number that can be shown on screen. To overcome this, the data is aggregated using one of 4 available methods: average, max, min, and sum.

Metrics

Your data source such as metrics, logs, or traces are the main focus of the graph. You can find the list of metrics available to you in the Metrics Summary. Click on any metric to see more detail about that metric, including the type of data collected, units, tags, hosts, and more.

Scope

A scope lets you filter a series. It can be a host, a device on a host, or any arbitrary tag you can think of that contains only alphanumeric characters, plus colons and underscores ([a-zA-Z0-9:_]+).

Examples of scopes and their meanings:

Scope Meaning
host:my_host Related to a given host.
host:my_host, device:my_device Related to a given device on a given host.
source:my_source Related to a given source.
my_tag Related to a tagged group of hosts.
my:tag Same as above.
* Wildcard for everything.

Groups

For any given metric, data may come from several hosts. The data is normally aggregated from all these hosts to a single value for each time slot. You can split these out by any tag. To include a data point separated by each host, use {host} for your group.

Arithmetic

You can apply simple arithmetic to a series (+, -, * and /).

The following example graphs 5-minute load and its double:

{
    "viz": "timeseries",
    "requests": [
        {
            "formulas": [
                {
                    "formula": "query1"
                },
                {
                    "formula": "2 * query1"
                }
            ],
            "queries": [
                {
                    "data_source": "metrics",
                    "name": "query1",
                    "query": "avg:system.load.5{*}"
                }
            ],
            "response_format": "timeseries",
            "type": "line",
            "style": {
                "palette": "dog_classic",
                "type": "solid",
                "width": "normal"
            }
        }
    ],
    "yaxis": {
        "scale": "linear",
        "min": "auto",
        "max": "auto",
        "include_zero": true,
        "label": ""
    },
    "markers": []
}

You can also add, subtract, multiply, and divide a series. Note: Datadog does not enforce consistency, so you can divide apples by oranges.

{"viz": "timeseries", "requests": [{"q": "metric{apples} / metric{oranges}"}]}

Examples

Here is the JSON for the above example showing average of network bytes received for a specific device and host and grouped by account.

"requests": [
        {
            "formulas": [
                {
                    "formula": "query1"
                }
            ],
            "queries": [
                {
                    "data_source": "metrics",
                    "name": "query1",
                    "query": "avg:system.net.bytes_rcvd{device:eth0,host:dsg-demo-1} by {account}"
                }
            ],
            "response_format": "timeseries",
            "type": "line",
            "style": {
                "palette": "dog_classic",
                "type": "solid",
                "width": "normal"
            }
        }
    ]

Here is an example using the rate() function, which takes only a single metric as a parameter.

    "viz": "timeseries",
    "requests": [
        {
            "formulas": [
                {
                    "formula": "per_hour(query1)"
                }
            ],
            "queries": [
                {
                    "data_source": "metrics",
                    "name": "query1",
                    "query": "avg:system.load.5{*} by {host}"
                }
            ],
            "response_format": "timeseries",
            "type": "line",
            "style": {
                "palette": "dog_classic",
                "type": "solid",
                "width": "normal"
            }
        }
    ]

Here is the same example as a top list.

{
    "viz": "toplist",
    "requests": [
        {
            "formulas": [
                {
                    "limit": {
                        "count": 10,
                        "order": "desc"
                    },
                    "formula": "query1"
                }
            ],
            "queries": [
                {
                    "data_source": "metrics",
                    "name": "query1",
                    "query": "avg:system.load.5{role:db} by {host}",
                    "aggregator": "avg"
                }
            ],
            "response_format": "scalar",
            "conditional_formats": []
        }
    ]
}

Here is an example using the week_before() Timeshift function:

    "viz": "timeseries",
    "requests": [
        {
            "formulas": [
                {
                    "formula": "week_before(query1)"
                }
            ],
            "queries": [
                {
                    "data_source": "logs",
                    "name": "query1",
                    "search": {
                        "query": ""
                    },
                    "indexes": [
                        "*"
                    ],
                    "compute": {
                        "aggregation": "count"
                    },
                    "group_by": []
                }
            ],
            "response_format": "timeseries",
            "type": "line"
        }
    ]

Here is another example showing how to graph a ratio of error to info logs and then apply a Timeshift function.

{
    "viz": "timeseries",
    "requests": [
        {
            "formulas": [
                {
                    "formula": "query1 / query2",
                    "alias": "Ratio of Error to Info"
                },
                {
                    "formula": "week_before(query1 / query2)"
                }
            ],
            "queries": [
                {
                    "data_source": "logs",
                    "name": "query1",
                    "search": {
                        "query": "status:error"
                    },
                    "indexes": [
                        "*"
                    ],
                    "compute": {
                        "aggregation": "count"
                    },
                    "group_by": []
                },
                {
                    "data_source": "logs",
                    "name": "query2",
                    "search": {
                        "query": "status:info"
                    },
                    "indexes": [
                        "*"
                    ],
                    "compute": {
                        "aggregation": "count"
                    },
                    "group_by": []
                }
            ],
            "response_format": "timeseries",
            "type": "line",
            "style": {
                "palette": "dog_classic",
                "type": "solid",
                "width": "normal"
            }
        }
    ],
    "yaxis": {
        "scale": "linear",
        "min": "auto",
        "max": "auto",
        "include_zero": true,
        "label": ""
    },
    "markers": []
}

Further Reading

Additional helpful documentation, links, and articles: