Dashboard builder

Design rich, reliable dashboards by composing widgets, self‑contained visual blocks that read from your telemetry and present it in the format you choose. This guide walks through the full widget workflow in the exact order you will experience it in the UI: creating a widget, selecting a graph type and time window, organising with groups, building queries and formulas, tuning roll‑ups, applying functions and advanced options (including a comprehensive unit system), and finally finishing the visual and layout polish.

1. Create a Dashboard#

To create a dashboard, go to Dashboard Builder → Create Dashboard → Give name and description. It will open a window giving you multiple widget options.

You can add a widget to an empty or an existing dashboard. On an empty dashboard, select one of the available widget types. The editor opens immediately with that type preselected. On a dashboard that already contains widgets, use "Add Widget" in the top-right corner; you will see the same list of types, and choosing one opens the widget editor.

2. Understand the Widget Editor#

When the editor opens, it is separated into three clear sections so you can set context, data, and visuals without losing your place:

• Top bar: Pick a preview time range so you can see the effect of your configuration on real data while you edit.
• Left panel: Name and describe the widget, optionally assign it to a Group with a Group Order, and choose the Graph Type. Treat this panel as the widget’s metadata and high‑level intent.
• Right panel: At the top, you see the live graph preview; below that, you configure Query Data, Formulas, Functions, and Advanced Options. This is where the widget actually connects to and transforms your data.

3. Choose an Appropriate Graph Type#

Middleware supports multiple visualizations, allowing the same metric to be inspected from different angles: Timeseries, Bar Chart, List Value, Query Value, Pie Chart, Scatter Plot, Tree Chart, Top List Chart, Heatmap Chart, Hexagon Chart, Split Graph, and Text Widget. Pick the type that matches the story you want to tell.

For example, Timeseries for change over time, Bar Chart to compare categories at a glance, Heatmap Chart to see how values spread across many groups over time, Top List Chart to surface the highest/lowest values, and Query Value to emphasise a single computed number.

Graph types fall into two families, and some query controls only appear for one of them:

• Time-based widgets: Timeseries (including Areas), Bar Chart (including Stacked Bars), Heatmap Chart, and Split Graph. These plot values over time.
• Single-value widgets: List Value, Query Value, Pie Chart, Top List Chart, Tree Chart, Scatter Plot, and Hexagon Chart. These show one value per group for the selected time range, and some of them offer Reduce values in timeframe to.

3.1 Display Preference (time window behaviour on the dashboard)#

Decide how the widget obeys time on the dashboard:

• Global Time (default): The widget inherits the dashboard’s time range so multiple widgets remain comparable.
• Past X: The widget always shows a trailing window you select (e.g., Past 1m/5m/15m/1h/3h/12h/1d/2d/1w), regardless of the dashboard range. Use this when a fixed recent context is essential (e.g., “last 15 minutes of errors”) and cross‑widget alignment is less important.

3.2 Group and Group Order (dashboard organisation)#

Use Group to collect related widgets into labelled sections. Set the Group Order to a number that controls the section's position; lower numbers appear earlier. To keep the group together, reuse the same order number for each widget in that group. Otherwise, widgets may interleave with other groups.

4. Build the data layer: Queries, Filters, Aggregation, and Groups#

A widget’s data is defined by one or more Queries and, if needed, one or more Formulas. Add as many as you require.

4.1 Query Data#

You can fill your graph with data using queries and formulas.

• Queries let you pull specific data from your selected resource.
• Formulas allow you to apply calculations or combine results from multiple queries.

You can add as many queries and/or formulas as needed to get the exact data you want to visualize.

Query row layout

Each query is laid out as a set of rows, from top to bottom:

1. Query row: Metric picker → field dropdown (HIST and EXP_HIST metrics) → second metric picker (attribute queries only) → from filters → aggregation dropdown → group by → Apply to all → hide / copy / delete.
2. Reduce values in timeframe to: Available on some widgets only, such as List Value (see 4.5).
3. Functions row: Applied function chips and the Add Function button (see 4.8).
4. Show/Hide Advanced Options: Roll Up, Alias Name, Unit and per.
5. Metric metadata info bar: Shown in the Dashboard Explorer only.

Below all queries, the widget-level Sort by and Limit controls apply to the whole widget (see 5.4).

4.2 Select the data source (Look For) #

Every piece of OpenTelemetry and monitoring data is attached to a resource such as a host, container, process, or service. Choose the resource that actually emits the metric you need. Look For defaults to All Metrics, which lets you search every metric regardless of resource. Only resources you have integrated are selectable; resources that exist but currently have no data are visible yet disabled to prevent misconfiguration.

4.3 Define the Query (Metric and Filter) #

Metric#

Choose the metric you want to display in the graph from the dropdown list or by searching for it. The list of metrics shown will be related to the resource you selected earlier.

Each metric in the list shows a badge for its instrument type:

• GAUGE: A value sampled at a point in time, such as memory usage or temperature.
• SUM: A running total or counter, such as requests served.
• HIST: A histogram of value distributions, such as request latency.
• SUMMARY: Pre-calculated quantiles reported by the source.
• EXP_HIST: An exponential histogram.

When you hover over an option in the dropdown, a panel on the right shows its resource, metric name, type, Unit, description (when available), and attributes. This helps you understand what each metric represents before selecting it.

If your search matches 100 or more results, Search for more... appears at the end of the list. Refine your search text to narrow the results.

Attribute queries (unique counts)#

Along with metrics, the metric picker also lists metric attributes (badge M_ATTR) and resource attributes (badge R_ATTR). Pick an attribute when you want to count how many distinct values it has rather than plot a metric.

When you pick an attribute:

1. The aggregation is set to uniq.
2. A second metric picker appears. Choose which metric's data points the attribute is read from.

For example, pick host.id as the attribute and system.cpu.utilization as the metric to get the unique count of hosts reporting CPU utilization.

Reduce values in timeframe to is available for attribute queries too.

Filter#

You can filter your metric’s data by attributes or other metrics using the from box (next to the metric selector).

Default Filter: (everywhere), shows combined data from all sources (e.g., hosts, processes, containers).

Custom Filter: Use advanced filtering to narrow results. You can build Boolean expressions in this format: <attribute or metric> <operator> <value>

Example: host.id != prod-machine

How to Use the From Box:#

1. Click inside the From box.
2. Type the attribute or metric name, or select it from the dropdown.
3. Choose an operator (suggestions will appear; you can type or select).
4. Enter the value to compare against (type it or pick from the dropdown).

The From box is smart; as you type, it will suggest valid attributes/metrics, operators, and values based on your selection, making filtering faster and easier.

Combining Multiple Filter Conditions#

You can create more complex filters by combining multiple Boolean expressions using AND or OR operators.

You can also group and nest conditions using round brackets () to control the order in which they are applied.

Example: (host.id != prod-machine AND os.type = mac) OR status = stop

AND and OR have the same precedence and are applied from left to right. For example, a = 1 OR b = 2 AND c = 3 is read as (a = 1 OR b = 2) AND c = 3, not a = 1 OR (b = 2 AND c = 3). Whenever you mix AND and OR, add brackets to make the order explicit.

Operators and the AND / OR keywords are case-insensitive, so in, like and and work the same as IN, LIKE and AND.

Supported operators:

4.4 Choose Aggregation and Aggregation Group#

At each timestamp, multiple instances (hosts, processes, containers) may report the same metric. Aggregation determines how those per-source points are reduced into one value per timestamp (the default is avg by). The options are avg by, sum by, min by, max by, last, uniq by, and count by.

The info icon next to the aggregation dropdown explains the two kinds of aggregation:

• Space aggregation: Combines multiple series into one series per group.
• Time aggregation: Combines multiple samples into one value per series.

How they work together

Take system.cpu.utilization from 3 hosts, reported every 10 seconds, viewed over 1 hour, with avg by host.name:

1. Time aggregation (Roll Up): Each host's 10-second samples are combined into larger buckets (see section 4.6). Each host is still its own series.
2. Space aggregation (avg by): At each bucket, series that share the same host.name are averaged together. The result is one line per host.

Remove the group by and step 2 averages all 3 hosts into a single line. Switch to max by and you get the busiest value in each group instead of the average.

For a step-by-step worked example, including how reducers turn a timeseries into one value, see Understanding Aggregations.

Numeric aggregations (avg, sum, min, max) are hidden when the query reads an attribute or string column.

What each option does across the series in a group:

• avg by, sum by, min by, max by: The average, total, lowest or highest value of the series at each timestamp.
• count by: How many series reported a value at each timestamp.
• uniq by: The approximate number of distinct values. Used mainly for attribute queries.
• last: The value of one of the series in the group, without a defined order between series. Use it when each group holds a single series, for example when you group by host.name and each host reports one series. The series label shows this aggregation as any(...).

Metric field

When you pick a histogram (HIST) or exponential histogram (EXP_HIST) metric, a field dropdown appears next to the metric picker. It offers bucket, count, sum, min, and max. Gauge and sum metrics have no field dropdown.

• With bucket, the aggregation offers percentiles: p50, p75, p90, p95 (default), and p99.
• With any other field, the aggregation offers avg, sum, min, max, and last.

If you want to compare instances side by side, use Aggregation Group. Select one or more attributes to group and each group will render as its own line, bar, list row, or element. For example, grouping by host yields one series per host in a timeseries chart, making instance comparisons effortless.

4.5 Reduce values in timeframe to (available on some widgets only) #

Widgets such as List Value show one number per group, not a line over time. The Reduce values in timeframe to row (shown with a clock icon) controls how the selected time range is collapsed into that one value. The options are avg, sum, min, max, and last.

For example, with a 1-hour time range and max, a List Value widget shows the highest value each group reached during that hour.

Where it appears

• Shown on: List Value, Query Value, Pie Chart, Top List Chart, Tree Chart, Scatter Plot, and Hexagon Chart.
• Not shown on: Timeseries, Bar Chart, Heatmap Chart, and Split Graph.
• It is also not shown for formulas, in alert builders, or for aggregations that cannot be reduced. It applies to avg, sum, min, max, uniq, and percentile aggregations.

Defaults

• New queries use avg.
• Switching a widget from a time-based chart to one that shows the reducer sets it to avg. Switching back to a time-based chart removes it.
• Widgets saved before this option existed show last, which is how their values were already computed, so their numbers do not change.

4.6 Control density with Roll-Up (aggregation over time) #

Metrics are usually collected in short intervals, typically every 5 to 20 seconds, by agents, integrations, or cloud services.

For example:

• If a metric is collected every 5 seconds, you will have 17,280 data points for one day of data.
• Due to physical limits, middleware graphs can only display about 200–300 data points at once. The system automatically aggregates your data into larger time blocks.
• Hence, 1-day data will be rolled up every 5 minutes, creating 288 data points, where each new point represents an average of 60 original data points.

By default, Middleware:

• Averages the metric values within each time bucket (Roll Up: Average)
• Uses a roll-up interval based on the length of the selected time range

To change this, open Show Advanced Options and use the Roll Up <fn> over <N> seconds row:

• Roll Up: The aggregation applied within each time bucket: Average, Sum, Minimum, Maximum, or Last (the most recent value in the bucket).
• over [N] seconds: The bucket size, e.g., 120 or 600. Leave it empty (placeholder auto) to use the default interval. The default interval for the time range is also the minimum: a smaller value is raised to it. For example, 60 over a 1-day range still gives 5-minute buckets. Buckets are never smaller than 30 seconds, whatever the time range.
• Apply to all: Applies this roll-up to all the queries in the widget.

For non-metric aggregations, the label reads Roll Up Over, and you set only the interval.

4.7 Compose results with Formulas#

Assign letters (a, b, c, …) to your queries, then write an expression that uses those letters as variables. For instance, to compute a percentage, you might write: (a / b) * 100

Rules:

• Each query must be represented by its assigned lower‑case letter symbol, or you will get an error.
• The formula must be a valid mathematical expression. It can use the query letters, numbers (for example 100 or 0.5), the operators +, -, * and /, and round brackets. Functions can't be used inside the expression; add them to the formula with Add Function instead.

How a formula is calculated

• The formula is evaluated separately for each group and each timestamp. Series are matched by their group-by values, so queries in a formula should use the same group by.
• Functions on the individual queries are applied first, then the formula is evaluated, then any functions added to the formula.
• If one of the queries has no value at a timestamp, the formula has no point there.
• Dividing by zero, or any result that isn't a finite number, gives 0, not a gap. Keep this in mind for ratios where the denominator can be zero, such as error rate with no traffic.

4.8 Transform results with Functions#

Functions transform the output of a query, for example turning a counter into a rate, smoothing a noisy line, or comparing against last week.

Add a function

1. Click Add Function in the functions row under the query.
2. The picker opens in three panes:
   • Categories on the left.
   • Functions in the selected category in the middle.
   • Preview on the right, with a description, a mini visualization, and the expression it produces, e.g. fn(metric).
3. Click a function to apply it. It appears as a chip in the functions row.

Work with function chips

• Functions that take arguments show inline inputs on the chip. An invalid number turns the input red.
• Click ✕ on a chip to remove the function.
• Functions run in the order they were added, except rate functions and timeshifts: they are part of the query itself, so they always run before the other functions.
• The same function can't be added twice to one query.
• Only one rate function is allowed per query. Picking another one replaces the current one.
• Only one timeshift (Hour before, Day before, or Week before) is allowed per query. Picking another one replaces the current one.
• A rate function always shows as the first chip in the row.

In the example below, query A has an ewma_3 chip applied and query B is the same metric without functions, so the chart compares the smoothed line (alias applied) with the raw one (alias original).

Function reference

The aggregator for Group By, and for the "by" argument of Top, can be avg, sum, min, max, count, median, stddev, last, p50, p75, p90, p95, or p99.

Common recipes

For example, system.cpu.load_average.1m is a gauge metric, so its Rate category lists Diff, Monotonic Diff, Derivative, Per Second, Per Minute, Per Hour, and Delta Time, without Rate or Increase.

Rate functions and units

The Rate category is especially useful when you need a change-per-interval view from a cumulative counter. When you pick a rate function, the unit's per is set for you:

• Rate, Per Second, and Derivative: /s
• Per Minute: /min
• Per Hour: /h
• Increase, Diff, Monotonic Diff, and Delta Time: no suffix

If the query has no unit, the metric's own unit is used. A per you set by hand is never overwritten, and units that are already rates don't get a second suffix.

Automatic rate for counters: On every graph type except List Value, including Query Value and Top List Chart, picking a monotonic SUM (counter) metric applies Rate automatically, with a /s unit. This happens when the query had no metric yet or a metric of another type. Switching from one sum metric to another keeps the functions you already have. Opening a saved widget never changes its query.

How the rate functions differ

Rate functions compare each bucket with the previous one, per series, after the roll-up. They differ in how they handle a drop in value, which on a counter usually means the process restarted and the counter reset:

For a sum metric with delta temporality, Rate and Increase don't compare buckets: each bucket's increments are added up, and Rate divides that by the bucket size in seconds.

After the per-series value is calculated, series are combined with the space aggregation (for example sum by) as usual.

Example of rate functions applied to a counter:

At 15:05 the counter dropped from 30 to 15, which is treated as a reset. Diff shows the signed change. Monotonic Diff and Per Second/Minute/Hour clamp it to 0. Rate would show 15 ÷ 60 = 0.25, and Increase 15.

5. Advanced Options#

Advanced controls tighten the final semantics and presentation of the widget.

5.1 Alias Name#

By default, your graph will use the selected metric name as the label for the line, column, or component that shows its data.

If you want a different label, you can enter a custom name in the Alias Name input box. This custom name will then appear in the graph legend and tooltips instead of the metric’s default name.

5.2 Unit (override default metric units) #

Most metrics ship with a default unit (for example, system.cpu.utilization renders as %). You can override this if your reporting requires different semantics. Open Show Advanced Options, locate Unit, and choose from the dropdown. Use per to make it a rate unit, e.g., /s. The widget immediately interprets and displays values using this unit.

Metrics without a configured display unit are formatted automatically from their OpenTelemetry unit on axes, tooltips, and table columns. A unit you choose always takes priority. Rate functions also set per automatically (see Rate functions and units). For the full list, see Customizing Metric Unit.

5.3 Visual Config#

In the Query Value graph, you can customize the color of the value and the background based on specific conditions using the Visual Config rules.

How to add a Visual Config rule:

1. Click the Add Visual Config button to create a new rule.
2. In the rule, specify these settings:
   • Operator: Choose an operator (like equals, greater than, less than) from the dropdown to compare against the value.
   • Value: Enter the number or value you want to compare the metric against.
   • Apply Color To: Select whether the color should change for the value itself or the background behind the value.
   • Color: Pick the color you want to apply, either by entering a hex code or selecting from the color picker.

Compare data with the previous time period

In the Query Value graph, you can also show the percentage change compared to the previous time period.

Example:

• Last hour's metric value: 25.45
• Last-to-last hour's metric value: 27.46
• Change: ~7.3% decrease (shown in the mid‑right corner of the graph)

How to enable this:

1. Click Show Advanced Options, then check the Show Comparison with Previous Time Period checkbox.
2. Next to Display comparison as, choose Success or Error to decide how the change should be displayed.

JSON Format

In the List Value graph, if the data is in JSON format (for example, a log body or message), you can extract and display the value of a specific field.

How to use JSON Format:

• Click Show Advanced Options on the query.
• Check the JSON Format checkbox.
• In the input box next to it, type the field name whose value you want to extract from the JSON.

The widget will then display the value from that specific JSON field as the complete value in the list.

5.4 Sort by and Limit#

Sort by and Limit sit below all the queries and apply to the whole widget. Use them to answer "which ones are worst?", for example the 10 hosts with the highest memory usage in a Top List.

Both are hidden on Query Value and on time-based widgets (Timeseries, Areas, Bar Chart, Stacked Bars, Heatmap Chart, and Split Graph). On those widgets, Heatmaps show up to 20 rows and other charts up to 100 series. These caps aren't a top-N: when a query returns more groups, which ones are shown isn't defined. To see the highest or lowest groups, add the Top function.

Sort by

In a List Value widget, you can sort the displayed data by clicking the column headers. This lets you quickly reorder the rows based on a metric or group name. However, this sorting only applies temporarily and will reset when you reload the page.

To make the sorting persistent across page reloads, use the Sort by dropdowns:

• First Dropdown: Select the metric or group name by which you want to sort the data. It defaults to the first query's metric.
• Second Dropdown: Choose the sorting order, ascending or descending. The default is descending.

If you clear Sort by, it shows Default.

Limit

List Value widgets on dashboards and in the widget editor preview don't paginate. They show all rows up to the Limit.

6. Additional Formatting#

This section gives you various options to customize how your data appears in the graph.

6.1 Display Options#

You can choose from multiple display options to fine tune the graph according to your preference.

• Timeseries Graph: You can choose how to show your data as either Lines (the default) or Areas.
  • Lines: Displays your data as connected points forming a line, showing trends over time clearly.
  • Areas: Fills the space underneath the line with color, helping to highlight the volume or magnitude of values over the timeline.

• Bar Graph: You can display your data in Bars (default) or Stacked Bars.
  • Bars: Shows each data series as separate side-by-side vertical bars.
  • Stacked Bars: Layer different data series on top of each other within the same bar, helping you see the total combined value as well as the contribution of each part.

Style

When using the Lines display type in your timeseries graph, you can customize the appearance of the line by choosing one of the following styles:

• Dash
• DashDot
• Dot
• LongDash
• LongDashDot
• LongDashDotDot
• ShortDash
• ShortDashDot
• ShortDashDotDot
• ShortDot
• Solid (default)

Stroke

You can adjust how thick or thin the line appears in your graph by changing the stroke width. The available options are: Normal (Default), Thick, or Thin.

Color

You can change the set of colors your graph uses by selecting a different color palette. This palette controls the colors applied to the lines, areas, bars, or other visual elements in your graph.

6.2 Y-Axis Controls#

In the timeseries or bar graph, you can configure the Y-axis as per your needs and data.

Scale Type

Choose how values on the Y-axis of your graph are scaled. The available scale types are:

• Linear (Default): Values increase in equal steps. Useful for most metrics. Example: 10, 20, 30, 40
• Logarithmic: Each step increases by a fixed factor (not a fixed difference). Good for data that spans wide ranges, like exponential growth or multiplicative change. Example: 0.1, 1, 10, 100, and so on.
• Datetime: Y-axis values represent time periods, useful if your metric is duration or timestamp-based. Example: 0.1 secs, 1 min, 10 mins, etc.

Min/Max

You can set the minimum and/or maximum value for the Y-axis in your graph. By default, the Y-axis range is set to Auto, adjusting automatically to fit your data.

Always include zero

If you have not specified a minimum value, you can select the Always Include Zero checkbox. This will force the Y-axis to start at zero, making it easier to compare values relative to a zero baseline.

Heatmap Y-Axis

Use a Heatmap when a query returns too many groups to read as separate lines. For example, CPU utilization grouped by k8s.pod.name across hundreds of pods is unreadable as a timeseries, but as a heatmap you can spot the hot pods and the times they ran hot.

The Heatmap graph shows time on the x-axis, rows on the y-axis, and the value as the cell color, with a gradient legend. Time is split into about 60 columns that cover the whole range. Buckets with no data are filled with 0, so a quiet period looks the same as a period where the value was 0.

Under Additional formatting → Y-Axis, choose what each row represents:

Heatmaps show up to 20 rows by default.

Group: one row per host, with the gradient legend on the right.

Value distribution: rows are value ranges, and each cell counts the hosts in that range.

6.3 Legend#

By default, your graph displays legends at the bottom-left corner that help you identify different groups of data. Legends are especially useful when you have multiple data groups and need to quickly understand what each represents.

You can choose from three different legend formats:

• Compact (Default): Shows only the group name for each data series.
• Extended: Shows the group name plus detailed statistics, including minimum, maximum, average, and sum values for each group in a table format. You may need to scroll within the graph area to see the complete table.
• None: Hides the legend completely.

You can temporarily hide specific data groups by clicking on their name in the legend. This is helpful when you want to focus on certain data series or reduce visual clutter. Click the legend name again to show the data group.

6.4 Markers#

In the Timeseries graph, markers draw fixed reference lines or bands on the chart, so anyone reading the widget can see at a glance whether a value is healthy. Find them in the Markers section, below Additional Formatting in the widget editor.

Example use cases:

• A red Line at 500 ms on a p95 latency widget to mark your SLO threshold.
• A green Range from 40 to 70 on a CPU utilization widget to mark the expected operating band.
• A warning line at 80 GB on a disk usage widget, set in GB even though the metric reports bytes.

Add a marker

1. Click Add Marker. Each marker gets a letter: A, B, C, and so on.
2. Set the options below.
3. To delete a marker, click Remove marker.

The y-axis expands to keep all markers visible. Editing markers doesn't re-run the query.