Timeseries Widget
New announcements from Dash: Incident Management, Continuous Profiler, and more! New announcements from Dash!

Timeseries Widget

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



  1. Choose the data to graph:

  2. Customize your graph with the available options.


Line graphs

Line graphs include two additional parameters:

StyleSolid, Dashed, Dotted
StrokeNormal, Thin, Thick


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:

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:

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.

Once enabled, events are overlayed on your graphs with red bars:

Y-axis controls

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

  • Add a second y-axis for visualizations that include more than one data set.
  • 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.

If your visualization includes more than one data set, you can add a second y-axis by expanding the Y-axis controls button. Click on + Add right y-axis and then specify which side each metric’s y-axis will correspond to under each metric’s configuration options. On the graph, you can isolate which part of the visualization corresponds with which y-axis by hovering over the y-axis of interest.

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

The following configuration options are available:

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.

Full screen

In addition to the standard full screen options, you can apply quick functions, compare to previous time periods, adjust the Y scale, save changes, or save as a new graph.

See Explore your data in full-screen graph mode, to learn more.


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

    "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"},
        "show_legend": {"type": "boolean"}
    "required": ["type", "requests"],
    "additionalProperties": false
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.
show_legendbooleanno(screenboard only) Show the legend for this 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"]}
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