Visualize values in ranges with gauge charts

Classic dashboards have their own panels and methods of configuring them. For details about panels in classic dashboards, see Classic dashboard panels.

A gauge chart visualizes numeric data returned by a query. The chart depicts a specified value, such as the last numeric value in a time series or the result’s sum, average, or minimum or maximum value, within a radial gauge representing a specified range.

Each gauge displays its series name or alias, the configured numeric value representing that series, and an indicator pointing to where that value falls within its range.

Two bars on the gauge indicate the gauge’s thresholds by their colors:

A thick bar indicates in which threshold the value falls.
A thin bar indicates the thresholds’ ranges on the gauge.

You can visualize the results of multiple queries in a single gauge chart panel to visually compare them. This can help you quickly identify whether values from related queries, such as resource usage of different services or cumulative failure and error counts, are within expected thresholds.

To create a gauge chart or learn more about the configuration options common to all panels, see Panels.

Gauge chart queries

Gauge charts use one or more queries to retrieve data to visualize. Gauge charts use the following query Options to refine the displayed information, depending on your Datasource:

Series naming: Select a method to filter for metrics:
- Labels require a Naming pattern. Use {{ label_name }} to include a label value. For example, {{ env }} will be replaced with values like staging-1, prod-1.
- Regex: Use a regular expression in the Regex text field to match a time series. You can also use a Naming pattern to rename series using capture groups.
Type: The PromQL query type: Instant, or Range.

Configure a gauge chart

You can configure a gauge chart by modifying its Settings.

Any changes you make in the panel’s Settings tab are immediately reflected in the Preview pane, but take effect only when you click Apply in the Edit panel interface and then Save the dashboard.

⚠️

Observability Platform doesn’t fully support directly editing a panel’s JSON representation and recommends configuring panels in the user interface. Use the JSON representation only for managing your configuration as code with tools such as Chronoctl and Terraform.

Modify a gauge chart’s visual representation

The Visual section in a gauge chart’s Settings tab controls how Observability Platform visualizes data in the gauge chart.

Mode: Select a display mode: Gauge or Bar.
Sort: Determines how the gauge chart sorts the rendered bars.
- Default sorts in the original data order.
- Ascending sorts from the lowest value at the top, to the highest value at the bottom. Descending sorts in the opposite direction.

Modify a gauge chart’s units and formatting

The Unit and formatting section in a table’s Settings tab defines how the gauge interprets and displays the panel’s query units.

Unit: Defines the unit used to render the Y axis. This has the most significant effect when you enable Abbreviate. Defaults to Decimal.
- Decimal: Base 10 values. Observability Platform renders a value of 1000000 as 1M.
- Bytes: As decimal multiple-byte units. Observability Platform renders a value of 1000000 as 1MB.
- Time: Determines the unit of time that Observability Platform uses to interpret a numeric value.
- Percent: Interprets the value as a percentile, representing 0% to 100% on a range of either 0.0 to 1.0 (Percent (0.0-1.0)) or 0 and 100 (Percent (0-100)).
  
  For example, Observability Platform renders a value of 1.0 in Percent (0.0-1.0) as 100%, and in Percent (0-100) as 1%.
Decimals: Defines how many decimal places Observability Platform renders for values. Default renders decimal places only if necessary and rounds to the nearest value. Numeric values from 0 to 4 render the corresponding number of decimal places.
Abbreviate: Toggles whether to abbreviate the gauge’s numeric value. For example, if enabled, Observability Platform renders a value of 100000000 as 100M. You can toggle this setting only if you set the Unit to Decimal or Bytes. Time units are always abbreviated and Percent values don’t require it. Defaults to true.

Modify a gauge chart’s thresholds

The Thresholds section in a gauge chart’s Settings tab defines values where Observability Platform renders each threshold range. You can define threshold values as either absolute numeric values or percentiles.

The threshold’s Mode defines whether all thresholds use Absolute numeric values, which is the default mode, or Percent values. Percent values are relative to the Y axis’ minimum and maximum.

Observability Platform assumes that the Default threshold always starts at the left-most beginning of the gauge’s range and end at the first threshold value. Each subsequent threshold value defines the end of the previous threshold’s range. Observability Platform also assumes the last threshold range begins at the last threshold value and ends at the right-most ending of the gauge’s range.

To create a new threshold value:

Click the plus sign (+) in the Thresholds section header.
In the field that displays, enter a value where you want Observability Platform to end the previous threshold range and begin the next range.
Click either Absolute or Percent to select the mode you want the panel to display.

⚠️
If you choose Absolute as the Mode and select any unit other than Percent, you must enter a maximum value in the Max field for the gauge chart to correctly display data. Otherwise, the chart has no upper limit and will display data incorrectly.
Optional: Click the color indicator, depicted as a colored circle, to open a color selector and choose a color for the threshold line.
Optional: Click the caret (>) to expand the threshold definition, and enter text in the Message field to display on the chart if the threshold is met.

To display only the text from the Message field, click the Show only message toggle.
In the Edit panel dialog, click Apply to save your changes.
After you’ve finished editing the panel, click Save on the dashboard to save your changes.

To delete a threshold value, click the caret (>) to expand the threshold definition, and then click the Delete icon on its corresponding row of the Thresholds section.

Bar chart Heat map