New announcements for Serverless, Network, RUM, and more from Dash!

Widget JSON schema

To learn more about the GUI editor, visit the main Graphing documentation Page.

Y-Axis schema

The Datadog y-axis controls allow you to:

  • Clip the y-axis to specific ranges
  • Filter series either by specifying a percentage or an absolute value
  • Change the y-axis scale from linear to log, sqrt, or power scale

The schema is:

AXIS_SCHEMA = {
    "type": "object",
    "properties": {
        "scale":        {"type": "string"},
        "min":          {"type": "string"},
        "max":          {"type": "string"},
        "include_zero": {"type": "boolean"}
    },
    "additionalProperties": false
}
ParameterTypeDescriptionDefault
scalestringSpecifies the scale type. Possible values: linear, log, sqrt, pow## (eg. pow2, pow0.5..)linear
minstringSpecifies minimum value to show on the y-axis. It takes a number, or auto for default behavior.auto
maxstringSpecifies the maximum value to show on the y-axis. It takes a number, or auto for default behavior.auto
include_zeroBoolean

Events schema

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

EVENTS_SCHEMA = {
    "type": "array",
    "items": {
        "type": "object",
        "properties": {
            "q": {"type": "string"},
        },
        "required": ["q"],
        "additionalProperties": false
    }
}

See the Event stream documentation to learn more about the <EVENT_QUERY> syntax.

Examples

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

"events": [
  {
    "q": "host:X tags:Y"
  }
]

or, if you’re looking to display all errors:

"events": [
  {
    "q": "status:error"
  }
]

Markers schema

Markers allow you to add visual conditional formatting for your graphs. The markers format is:

MARKERS_SCHEMA = {
    "type": "array",
    "items": {
        "type": "object",
        "properties": {
            "value":        {"type": "string"},
            "display_type": {"type": "string"},
            "label":        {"type": "string"}
        },
        "required": ["value"],
        "additionalProperties": false
    }
}
ParameterTypeDescription
valuestringValue to apply. Can be a single value y = 15 or a range of values 0 < y < 10
display_typestringCombination of:
- A severity error, warning, ok, or info
- A line type: dashed, solid, or bold
labelstringLabel to display over the marker.

Example:

The following markers:

Are applied with the following configuration:

{ (...)
  "widgets": [
    {
      "definition": {
        "markers": [
          {
            "display_type": "ok dashed",
            "label": "OK",
            "value": "0 < y < 50"
          },
          {
            "display_type": "error dashed",
            "label": "ALERT",
            "value": "y > 80"
          },
          {
            "display_type": "warning dashed",
            "label": "WARNING",
            "value": "50 < y < 80"
          }
        ],
        "requests": [(...)],
        "title": "CPU with markers",
        "type": "timeseries"
      },
(...)
},

Conditional format schema

Conditional formats allow you to set the color of your widget content or background, depending on a rule applied to your data.

CONDITIONAL_FORMATS_SCHEMA = {
    "type": "array",
    "items": {
        "type": "object",
        "properties": {
            "comparator":      {"enum": [">", ">=", "<", "<="]},
            "value":           {"type": "number"},
            "palette":         {"enum": ["blue","custom_bg","custom_image","custom_text","gray_on_white","green","green_on_white","grey","orange","red","red_on_white","white_on_gray","white_on_green","white_on_red","white_on_yellow","yellow_on_white",
            ]},
            "custom_bg_color": {"type": "string"},
            "custom_fg_color": {"type": "string"},
            "image_url":       {"type": "string", "format": "uri"},
        },
        "required": ["comparator", "value", "palette"],
        "additionalProperties": false
    }
}
ParameterTypeDescription
comparatorenumComparator to apply from: >, >=, <, or <=
valuedoubleValue for the comparator.
palettestringColor palette to apply; choose from blue, custom_bg, custom_image, custom_text, gray_on_white, green, green_on_white, grey, orange, red, red_on_white, white_on_gray, white_on_green, white_on_red, white_on_yellow, or yellow_on_white
custom_bg_colorstringColor palette to apply to the background, same values available as palette.
custom_fg_colorstringColor palette to apply to the foreground, same values available as palette.
image_urlstringDisplays an image as the background.

Time schema

The available timeframes depend on the widget you are using, but the general format for time is:

TIME_SCHEMA = {
    "type": "object",
    "properties": {
        "live_span": {"enum": [
            '1m',
            '5m',
            '10m',
            '15m',
            '30m',
            '1h',
            '4h',
            '1d',
            '2d',
            '1w',
            '1mo',
            '3mo',
            '6mo',
            '1y',
            'alert'
        ]}
    },
    "additionalProperties": false
}
ParameterTypeDescription
live_spanstringA short name to represent a timeframe value. Available values are:
-1m: 1 minute
-5m: 5 minutes
-10m: 10 minutes
-15m: 15 minutes
-30m: 30 minutes
-1h: 1 hour
-4h: 4 hours
-1d: 1 day
-2d: 2 days
-1w: 1 week
-1mo: 1 month
-3mo: 3 months
-6mo: 6 months
-1y: 1 year
-alert: used in the alert_graph widget only

Example

For instance, to indicate that you want a 10-minute timeframe, use the following:

"time": {
  "live_span": "10m"
}

Further Reading

Additional helpful documentation, links, and articles: