graphing.html

---
title: Graphing Primer
sidebar:
  nav:
    - header: Graphing Primer
    - text: Find the Graph Editor
      href: "#editor"
    - text: Grammar
      href: "#grammar"
    - text: Arithmetic & Functions
      href: "#functions"
---

<h2 id="editor">Find the Graph Editor</h2>

On each graph you will find a cog icon that open the graph editor.

<img src="/static/images/series-overlay-annotated.png" style="width:100%; border:1px solid #777777"/>

The graph editor has 2 tabs, "Edit" and "JSON". The "JSON" tab is the most flexible and powerful.
It lets you finely control what is displayed on the graph.

<img src="/static/images/json-editor.png" style="width:100%; border:1px solid #777777"/>

<h2 id="grammar">Grammar</h2>

The graph definition language is well-formed JSON and is structured in 2 parts:

1. Events
2. Time Series, a.k.a. Series

Here is how they fit together in a JSON dictionary:

    {
      "requests": [
        {
          "q": "metric{scope}"
        }
      ],
      "events": [
        {
          "q": "search query"
        }
      ]
    }

In other words at the highest level the JSON structure is a dictionary with 2 entries:

1. "events"
2. "requests"

### Events

You can overlay any event from Datadog. The general format is:

    "events": "search query"

For instance to indicate that you want events for machine X and tag Y:

    "events": "host:X tags:Y"

or if you're looking to display all errors:

    "events": "status:error"


### Scope

A scope lets you filter 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-Z1-9:_]+`).

Examples of scope (meaning in parenthesis):

    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)
    *                                 (wildcard for everything)

### Series

The general format of a Series is:

    function(metric{scope} [by {group}])

The `function` and `group` are optional.

Series can be further combined together via binary operators (+, -, /, *):

    metric{scope} [by {group}] operator metric{scope} [by {group}]

Series are represented in 2 representatinos:

1. as line charts
2. as stacked areas
3. as slice-n-stack areas

#### Line Charts

<img src="/static/images/multi-lines.png" style="width:100%; border:1px solid #777777"/>

The representation is automatically derived from having multiple `requests` values.

    "requests": [
        {
          "q": "metric1{scope}"
        },
        {
          "q": "metric2{scope}"
        },
        {
          "q": "metric3{scope}"
        }
      ]

#### Stacked Series

<img src="/static/images/slice-n-stack.png" style="width:100%; border:1px solid #777777"/>

In the case of related time series you can easily draw them as stacked areas by using the following syntax:

    "requests": [
        {
          "q": "metric1{scope}, metric2{scope}, metric3{scope}"
        }
    ]

Instead of one query per chart you aggregate all queries into one and simply concatenate the queries.

#### Slice-n-Stack

A useful visualization is to represent a metric shared across
hosts and stack the results. For instance when selecting a tag that
applies to more than 1 host you will see that ingress and egress
traffic is nicely stacked to give you the sum as well as the split per
host. Useful to spot wild swings in the distribution of network
traffic.

Here's how to do it for any metric:

    "requests" [
      {
         "q": "system.net.bytes_rcvd{some_tag, device:eth0} by {host}"
      }
    ]

Note that in this case you can only have 1 query. But you can also split by device, or a combination of both:

    "requests" [
      {
         "q": "system.net.bytes_rcvd{some_tag} by {host,device}"
      }
    ]

to get traffic for all the tagged hosts, split by host and network device.

<h2 id="functions">Arithmetic and Functions</h2>

Series also support simple arithmetic and a number of functions.

You can apply functions to metric queries in the graph editor, as long as you
use the JSON editor.

### Arithmetic

You can apply simple arithmetic to Series (+, -, * and /). In this
example we graph 5-minute load and its double.

    {
      "viz": "timeseries",
      "requests": [
        {
          "q": "system.load.5{intake} * 2"
        },
        {
          "q": "system.load.5{intake}"
        }
      ]
    }

You can also add, substract, multiply and divide series. Beware that
Datadog does not enforce consistency at this point so you *can* divide
apples by oranges.

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

### Functions

You can apply functions to the result of each query.

<table class="table">
  <tr>
    <th>Function</th>
    <th>Description</th>
  </tr>

  <tr>
    <td>dt()</td>
    <td>time delta between points</td>
  </tr>

  <tr>
    <td>diff()</td>
    <td>value delta between points</td>
  </tr>

  <tr>
    <td>derivative()</td>
    <td>1st order derivative, diff / dt</td>
  </tr>

  <tr>
    <td>rate()</td>
    <td>1st order derivate that skips non-monotonically increasing values</td>
  </tr>

  <tr>
    <td>derived()</td>
    <td>synonym for derivative</td>
  </tr>

  <tr>
    <td>per_second()</td>
    <td>synonym for rate</td>
  </tr>

  <tr>
    <td>per_minute()</td>
    <td>60 * rate</td>
  </tr>

  <tr>
    <td>per_hour()</td>
    <td>3600 * rate</td>
  </tr>

  <tr>
    <td>ewma_3()</td>
    <td>Exponentially Weighted Moving Average with a span of 3</td>
  </tr>

  <tr>
    <td>ewma_5()</td>
    <td>EWMA with a span of 5</td>
  </tr>

  <tr>
    <td>ewma_10()</td>
    <td>EWMA with a span of 10</td>
  </tr>

  <tr>
    <td>ewma_20()</td>
    <td>EWMA with a span of 20</td>
  </tr>
</table>