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

Timeseries Widget

The timeseries visualization allows you to display the evolution of one or more metrics, log events, or APM events over time. The time window depends on what is selected on the timeboard or screenboard:

Setup

Configuration

  1. Choose the data to graph:

  2. Customize your graph with the available options.

Options

Line graphs

Line graphs include two additional parameters:

ParameterOptions
StyleSolid, Dashed, Dotted
StrokeNormal, Thin, Thick

Appearance

Graphs can be displayed as areas, bars, or lines. For all graph types, Datadog offers various color options to differentiate multiple metrics displayed on the same graph:

PaletteDescription
ClassicThe simple colors light blue, dark blue, light purple, purple, light yellow, and yellow (colors repeat).
CoolA gradient color scheme made from green and blue.
WarmA gradient color scheme made from yellow and orange.
PurpleA gradient color scheme made from purple.
OrangeA gradient color scheme made from orange.
GrayA gradient color scheme made from gray.

For line graphs, different metrics can be assigned specific palettes by separating the queries in JSON.

Metric aliasing

Each query or formula can be aliased. The alias overrides the display on the graph and legend, which is useful for long metric names. At the end of the query/formula click on as…, then enter your metric alias:

Event Overlay

Add events from related systems to add more context to your graph. For example, you can add GitHub commits, Jenkins deploys, or Docker creation events. Expand the Event Overlays section and enter a query to display those events. Use the same query format as for the Event Stream, for example:

QueryDescription
sources:jenkinsShows all events from the Jenkins source.
tag:role:webShows all events with the tag role:web.
tags:$<TEMPLATE_VARIABLE>Shows all events from the selected Template Variable.
Y-axis controls

Y-axis controls are available via the UI and the JSON editor. They allow you to:

  • Clip the y-axis to specific ranges.
  • Automatically change y-axis bounds based on a percentage or an absolute value threshold. This threshold can be applied to one of both ends of the graph (lower and upper) in order to remove “outliers” series.
  • Change the y-axis scale from linear to log, pow, or sqrt.

Change the Y-axis scale by expanding the Y-Axis Controls button.

The following configuration options are available:

OptionRequiredDescription
Min/MaxNoSpecify the minimum and/or maximum value to show on y-axis. It takes a number or Auto as the default value.
ScaleNoSpecifies the scale type. Possible values:
- linear: A linear scale (default)
- log: A logarithmic scale
- pow: A Power of 2 scale (2 is default, modify in JSON)
- sqrt: A square root scale
Always include zeroNoAlways include zero or fit the axis to the data range. The default is to always include zero.

Note: Because the mathematical log function doesn’t accept negative values, the Datadog log scale only works if values are of the same sign (everything > 0 or everything < 0). Otherwise an empty graph is returned.

API

The dedicated widget JSON schema definition for the timeseries widget is:

TIMESERIES_SCHEMA = {
    "type": "object",
    "properties": {
        "type": {"enum": ["timeseries"]},
        "requests": {
            "type":    "array",
            "items":   REQUEST_SCHEMA,
            "minItems": 1
        },
        "yaxis":   AXIS_SCHEMA,
        "events":  EVENTS_SCHEMA,
        "markers": MARKERS_SCHEMA,
        "title":   {"type": "string"}
    },
    "required": ["type", "requests"],
    "additionalProperties": false
}
ParameterTypeRequiredDescription
typestringyesType of widget, for the timeseries widget use timeseries.
requestsarray of objectsyesArray of request object to display in the widget. See the dedicated Request JSON schema documentation to learn how to build the REQUEST_SCHEMA.
yaxisobjectnoY-axis control options. See the dedicated Y-axis JSON schema documentation to learn how to build the AXIS_SCHEMA.
eventsobjectnoEvent overlay control options. See the dedicated Events JSON schema documentation to learn how to build the EVENTS_SCHEMA
markersobjectnoMarkers overlay control options. See the dedicated Markers JSON schema documentation to learn how to build the MARKERS_SCHEMA
titlestringnoTitle of your widget.

Additional properties allowed in each request object:

{
    "style": {
        "type": "object",
        "properties": {
            "palette":    {"type": "string"},
            "line_type":  {"enum": ["dashed", "dotted", "solid"]},
            "line_width": {"enum": ["normal", "thick", "thin"]}
        },
        "additionalProperties": false
    },
    "metadata": {
        "type": "array",
        "items": {
            "type": "object",
            "properties": {
                "expression": {"type": "string"},
                "alias_name": {"type": "string"}
            },
            "required": ["expression"],
            "additionalProperties": false
        }
    },
    "display_type": {"enum": ["area", "bars", "line"]}
}
ParameterTypeRequiredDescription
style.palettestringnoColor palette to apply to the widget.
style.line_typestringnoType of lines displayed. Available values are: dashed, dotted, or solid.
style.line_widthstringnoWidth of line displayed. Available values are: normal, thick, or thin.
metadataobjectnoUsed to define expression aliases.
display_typestringnoType of display to use for the request. Available values are: area, bars, or line.

Further Reading