docs/sources/visualizations/panels-visualizations/visualizations/gauge/index.md
Gauges are single-value visualizations that allow you to quickly visualize where a value falls within a defined or calculated min and max range. With repeat options, you can display multiple gauges, each corresponding to a different series, column, or row.
{{< figure src="/media/docs/grafana/panels-visualizations/screenshot-gauge-visualization-v13.0.png" alt="A gauge visualization">}}
You can use gauges if you need to track:
The following video provides beginner steps for creating gauge panels. You'll learn the data requirements and caveats, special customizations, and much more:
{{< youtube id="S3qJ1cuWHkI" >}}
{{< docs/play title="Grafana Gauge Visualization" url="https://play.grafana.org/d/KIhkVD6Gk/" >}}
To create a gauge visualization you need a dataset containing at least one numeric field. These values are identified by the field name. Additional text fields aren't required but can be used for identification and labeling.
The gauge visualization can support multiple fields in a dataset. <!-- In this case, multiple gauges are displayed. -->
| value1 | value2 | value3 |
|---|---|---|
| 5 | 3 | 10 |
When there are multiple values in the dataset, the visualization displays multiple gauges and automatically defines the minimum and maximum. In this case, those are 3 and 10. Because the minimum and maximum values are defined, each gauge is shaded in to show that value in relation to the minimum and maximum.
The gauge visualization can display datasets with multiple rows of data or even multiple datasets.
| Identifier | value1 | value2 | value3 |
|---|---|---|---|
| A | 5 | 3 | 10 |
| B | 6 | 9 | 15 |
| C | 1 | 4 | 8 |
By default, the visualization calculates a single value per column or series and displays only the last row of data. However, it derives the minimum and maximum from the full dataset, even if those values aren't visible.
In this example, that means only the last row of data, row C, is displayed in the gauges and the minimum and maximum values are 1 and 15. The value 1 is displayed because it's in the last row, while 15 is not.
If you want to show one gauge per table cell, under Value options, change the Show setting from Calculate to All values. Each gauge label is a concatenation of the text column with each value's column name.
You can control the minimum and maximum values by defining them directly in your dataset. This is an alternative to setting it manually in the field options.
| value | max | min |
|---|---|---|
| 5 | 10 | 2 |
In this example, to hide the min and max fields, select the "value" field in Value options > Fields.
Even when minimum and maximum values aren't displayed, the visualization still pulls the range from them.
{{< docs/shared lookup="visualizations/config-options-intro.md" source="grafana" version="<GRAFANA_VERSION>" >}}
{{< docs/shared lookup="visualizations/panel-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
Use the following options to refine how your visualization displays the value:
<!-- prettier-ignore-start -->| Option | Description |
|---|---|
| Show | Set how Grafana displays your data. Choose from:<ul><li>Calculate - Show a calculated value based on all rows.</li><li>All values - Show a separate value for every row. If you select this option, then you can also limit the number of rows to display.</li></ul> |
| Calculation | If you chose Calculate as your Show option, select a reducer function that Grafana will use to reduce many fields to a single value. For a list of available calculations, refer to Calculation types. |
| Limit | If you chose All values as your Show option, enter the maximum number of rows to display. The default is 25 and the maximum is 5,000. |
| Fields | Select the fields display in the panel. |
Adjust how the gauge is displayed.
<!-- prettier-ignore-start -->| Option | Description |
|---|---|
| Style | Choose a gauge shape:<ul><li>Circle - Fills clockwise around a circle, starting from the 12 o'clock position.</li><li>Arc - Fills from left to right around an arc.</li></ul> |
| Orientation | Choose a stacking direction:<ul><li>Auto - Gauges display in rows and columns.</li><li>Horizontal - Gauges display top to bottom.</li><li>Vertical - Gauges display left to right.</li></ul> |
| Gauge size | Choose a gauge size mode:<ul><li>Auto - Grafana determines the best gauge size.</li><li>Manual - Manually configure the gauge size.</li></ul>This option only applies when Orientation is set to Horizontal or Vertical. |
| Min width | Set the minimum width of vertically oriented gauges. If you set a minimum width, the x-axis scroll bar is automatically displayed when there's a large amount of data. This option only applies when Gauge orientation is Vertical and Gauge size is set to Manual. |
| Min height | Set the minimum height of horizontally oriented gauges. If you set a minimum height, the y-axis scroll bar is automatically displayed when there's a large amount of data. This option only applies when Gauge orientation is Horizontal and Gauge size is set to Manual. |
| Bar width factor | Set a factor between 0.1 and 1 to control the width of the gauge bar relative to the total gauge area. |
| Segments | Enter a value between 1 and 100 to break the gauge into equal segments. Segments are always fully filled, even if the gauge's current value falls within a segment. |
| Bar style | Choose the shape of the gauge bar. Choose from Flat or Rounded. Only applies if Segments is set to 1. Note: All segmented gauges are flat. |
| Segment spacing | Enter a value between 0 and 1 to set the factor that controls the size of the gap between each segment. This option is only applies when the Segments value is more than 1. |
| Text mode | Choose what text to render in the gauge:<ul><li>Auto - Grafana determines the text to show.</li><li>Value and name - Renders both the value and series name.</li><li>Value - Renders only the value.</li><li>Name - Renders only the series name.</li><li>None - Renders the gauge with no labels.</li></ul> |
| Neutral value | Set the starting value from which every gauge will be filled. |
| Show sparkline | Toggle on the switch to render a sparkline containing the series data for the gauge. This option is on by default. |
| Show thresholds | Control whether a threshold band is shown outside the inner gauge value band. |
| Show labels | Control whether threshold and neutral labels are shown outside of the gauge. |
| Endpoint marker | Choose how to mark the current value endpoint. Choose from Point, Glow, or None. Glow is available only in dark mode. This option only applies when the Bar style is Rounded. |
| Effects | Other styling choices you can apply to your gauge include: <ul><li>Gradient - Color transitions are represented with gradients for color schemes where the gauge color differs by value. This effect is on by default.</li><li>Bar glow - Adds a glowing shadow outside the gauge bar.</li><li>Center glow - The color representing the current gauge value is visible in the center of the gauge.</li></ul> |
By default, the starting value of a gauge is the minimum value, not zero. You can change the starting value from which every gauge will be filled when you don't want it to be the minimum value. This option is especially useful in cases where the range of data values includes negative numbers. If you leave this empty, Grafana uses the configured minimum value.
For example, you want to display the storage of several batteries and the power range is from -2.5 kW (discharging) to 2.5 kW. When the minimum value is used as the starting point for the gauges, the visualization looks like this:
If you enter a neutral value of 0, the visualization looks like this and is easier to reason about:
If you want to visualize the list of values as a time series along with the calculated gauge value, toggle on the Show sparkline switch. Each gauge displays the sparkline inside the circle or arc:
Control whether a threshold band is shown outside the inner gauge value band.
Adjust the sizes of the gauge text.
{{< docs/shared lookup="visualizations/standard-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
{{< docs/shared lookup="visualizations/datalink-options-1.md" source="grafana" version="<GRAFANA_VERSION>" >}}
{{< docs/shared lookup="visualizations/value-mappings-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}
{{< docs/shared lookup="visualizations/thresholds-options-2.md" source="grafana" version="<GRAFANA_VERSION>" >}}
{{< docs/shared lookup="visualizations/overrides-options.md" source="grafana" version="<GRAFANA_VERSION>" >}}