The Service Map for APM is here!

Widgets

Use widgets through the Screenboard API: For create/read/update endpoints, the body is one JSON payload describing the Screenboard widgets:

Base Payload :

# Replace the API and/or APP key below
# with the ones for your account

{
  "board_title": "My Board",

  // Options, e.g.: height, width, etc.

  "widgets": [
    // Put a list of widgets here.
  ]
}

Each type of widget is described below:

Timeseries

Supported on Screenboards and Timeboards

The Timeseries visualization allows you to show one or more metrics, Log events, or APM events evolution over time. The time window depends on what is selected on the Timeboard or in the graph on a Screenboard. Timeseries can be displayed as lines, areas, and bars.

Note: Define the Log Analytics query exactly as in the Log Explorer.

Timeseries

Example of Timeseries widget for the API

{
  "viz": "timeseries",

  // Title
  "title": true,
  "title_size": 16,
  "title_align": "left",
  "title_text": "My Metric (m/s)",

  // Sizing
  "height": 13,
  "width": 47,

  // Positioning
  "y": 28,
  "x": 32,

  // Widget Parameters
  "time": {
    "live_span": "1h" // Choose from: [1m, 5m, 10m, 15m, 30m, 1h, 4h, 1d, 2d, 1w, 1mo, 3mo, 6mo, 1y]
  },
  "tile_def": {
    "viz": "timeseries",
    "requests": [
      {
         "q": "sum:my.important.metric{*} by {host}"
      }
    ],
    "events": [
      {
        "q": "tags:release"
      }
    ]
  }
}

Overlay events on your graph

You can correlate Events to Metrics on Dashboards thanks to the Event Overlay Feature.

Via the UI Editor

event_overlay_ui

Via the JSON tab

event_overlay_json

In addition to being able to overlay events within the UI dashboard editor through the search field, you can also modify the JSON to add any event from Datadog. The general format is:

  • "events": "search query"

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

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

or if you’re looking to display all errors:

  • "events": "status:error"

Query Value

Supported on Screenboards and Timeboards

Query values display the current value of a given metric query, with conditional formatting (such as a green/yellow/red background) to convey whether or not the value is in the expected range. The value displayed by a query value need not represent an instantaneous measurement. The widget can display the latest value reported, or an aggregate computed from all query values across the time window. These visualizations provide a narrow but unambiguous window into your infrastructure.query

Query value widget

Example of Query Value widget for the API

{
  "viz": "query_value",

  // Title
  "title": true,
  "title_size": 16,
  "title_text": "Throughput",
  "title_align": "left",

  // Sizing
  "height": 4,
  "width": 14,

  // Positioning
  "y": 21,
  "x": 65,

  // Widget Parameters
  "aggregator": "avg", // Choose from: [avg, sum, min, max]
  "query": "sum:dd.sobotka.throughput.actual{*}",
  "conditional_formats": [
    {
      "color": "white_on_green",
      "invert": false,
      "comparator": ">", // Choose from: [>, >=, <, <=]
      "value": 20000
    }
  ],
  "text_align": "left",
  "precision": 1,
  "time": {
    "live_span": "1h" // Choose from: [1m, 5m, 10m, 15m, 30m, 1h, 4h, 1d, 2d, 1w, 1mo, 3mo, 6mo, 1y]
  },
  "text_size": "auto",
  "unit": "/s" // Give a custom unit or use "auto"
}

What does “Take the X value from the displayed timeframe” mean?

query_value_widget

The Query Value Widget only displays one Value, unlike a timeseries for example, that displays several points.

Let’s say you are on a Timeseries and you are currently displaying the past hour, this button allows you to either display the avg / max / min / avg / sum / last value of ALL points that are rendered during that 1 hour range timeframe - depending on the aggregation chosen above.

Scatter Plot

Supported on Screenboards and Timeboards

The scatter plot visualization allows you to graph a chosen scope over 2 different metrics with their respective aggregation:

  • Select a metric and an aggregation for the X and Y axis.
  • Define the scope for each point of the scatter plot, such as host, service, app, region, etc.
  • Enable a color-by tag (optional).
  • Set X and Y axis controls (optional).

Example graph:

Scatter Plot

Heat Map

Supported on Screenboards and Timeboards

The heat map visualization is great for showing metrics aggregated across many tags, such as hosts. The more hosts that have a particular value, the darker that square is.

Heat Map

Distribution

Supported on Screenboards and Timeboards

The Distribution visualization is another way of showing metrics aggregated across many tags, such as hosts. Unlike the heat map, distribution’s x-axis is the quantity rather than time.

Distribution

Top List

Supported on Screenboards and Timeboards

The top list visualization is perfect when you want to see the list of hosts with the most or least of any metric value, such as highest consumers of CPU, hosts with the least disk space, etc.

Note: Define the Log Analytics query exactly as in the Log Explorer.

Top List

Log Stream

Supported on Screenboards

The Log Stream displays a log flow matching the defined query:

Log stream

Note: You can choose which columns to display in the Log Stream widget.

Change

Supported on Screenboards and Timeboards

The Change graph shows you the change in a value over the time period chosen.

Change graph

Host Map

Supported on Screenboards and Timeboards

The host map graphs any metric for any subset of hosts on the same host map visualization available from the main Infrastructure Host Map menu.

Host Map

Free Text

Supported on Screenboards only

Free text is a widget that allows you to add headings to your Screenboard.

This is commonly used to state the overall purpose of the dashboard.

Event Timeline

Supported on Screenboards only

The event timeline is a widget version of the timeline that appears at the top of the Event Stream view.

Timeseries

Event Stream

Supported on Screenboards only

The event stream is a widget version of the stream of events on the Event Stream view.

Timeseries

This widgets displays only the 100 most recent events

Example of Event Stream widget for the API

{
    "viz": "event_stream"

    // Title
    "title": false,

    // Sizing
    "height": 57,
    "width": 59,

    // Positioning
    "y": 18,
    "x": 84,

    // Widgets Parameters
    "query": "tags:release",
    "time": {
      "live_span": "1h" // Choose from: [1m, 5m, 10m, 15m, 30m, 1h, 4h, 1d, 2d, 1w, 1mo, 3mo, 6mo, 1y]
    }
}

Image

Supported on Screenboards only

Image allows you to embed an image on your dashboard. Images can be PNG, JPG, or even animated GIF files.

Example of Image widget for the API

{
  "viz": "image",

  // Sizing
  "height": 20,
  "width": 32,

  // Positioning
  "y": 7,
  "x": 32

  // Widget Parameters
  "url": "http://path/to/image.jpg" // Note that you shouldn't hotlink to images you don't own.
}

Note

Supported on Screenboards only

Note widget is similar to Free Text widget, but allows for more formatting options:

  • An arrow can be added to the text box that appears on the dashboard. This is commonly used to document the structure of the dashboard.

  • Use href to create internal links in Datadog.

    Using links in note widget

Example of Note widget for the API

{
    "viz": "note",

    // Title
    "title": false,

    // Sizing
    "height": 15,
    "width": 30,

    // Positioning
    "x": 1,
    "y": 28,

    // Widget Parameters
    "html": "Put your note text in here.",
    "text_align": "left",
    "font_size": 14,
    "bgcolor": "yellow", // Choose from: [yellow, blue, pink, gray, white, red, green]
    "tick": true,
    "tick_pos": "50%",
    "tick_edge": "right" // Choose from: [top, right, bottom, left]
    "auto_refresh": true // Defaults to false
}

Alert Graph

Supported on Screenboards only

Alert graphs are timeseries graphs showing the current status of any monitor defined on your system.

Example of Alert Graph widget for the API

{
   "title_size": 16,
   "viz_type": "timeseries",
   "title": true,
   "title_align": "left",
   "title_text": "u",
   "height": 13,
   "width": 47,
   "alert_id": "<ENTER ID>",
   "time": {
    "live_span": "1h" // Choose from: [1m, 5m, 10m, 15m, 30m, 1h, 4h, 1d, 2d, 1w, 1mo, 3mo, 6mo, 1y, alert]
   },
   "y": 2,
   "x": 6,
   "isShared": false,
   "viz": "alert_graph",
   "add_timeframe": false
}

Alert Value

Supported on Screenboards only

Alert values are query values showing the current value of the metric in any monitor defined on your system.

Iframe

Supported on Screenboards only

The Iframe widget allows you to embed a portion of any other web page on your dashboard.

Check Status

Supported on Screenboards only

Check status shows the current status or number of results for any check performed.

Service Summary

Supported on Screenboards only

The service summary displays the top portion of any APM trace in your Screenboard.

Timeseries

Monitor Summary

Supported on Screenboards only

Monitor summary is a summary view of all monitors on your system, or a subset based on a query.

Timeseries

Further Reading