Build gauge charts with Kibana

Gauge charts display a single value within a defined range, showing how close the value is to a target or threshold. They are ideal for monitoring KPIs, tracking progress toward goals, and highlighting when values fall within acceptable, warning, or critical ranges. Unlike metric charts that display raw values, gauge charts add range context with known minimum and maximum boundaries.

You can build a gauge chart in Kibana in either of these ways:

• With the point-and-click editor
• With an ES|QL query

To automate chart or dashboard creation, use the Dashboards and Visualizations APIs. To create dashboards from natural-language instructions, use Elastic Agent Builder or the Kibana dashboards agent skill.

Before you start, make sure you have data indexed into Elasticsearch or install sample data. The point-and-click editor uses data views to access your Elasticsearch data. Data views are usually created automatically when you ingest data. You can also create one manually to select the data that you want.

To build a gauge chart:

Before you start, make sure you have data indexed into Elasticsearch or install sample data. ES|QL queries the indices named in the query directly, so you do not need a data view. The columns returned by the query become available as chart dimensions. Refer to Visualizations using ES|QL queries to learn how to open the editor, shape the query result for a visualization, and save the visualization.

A gauge chart needs a single numeric metric to position its indicator within the configured range. In this query, STATS has no BY clause, so it reduces all matching documents to one row containing the average number of bytes per request:

FROM kibana_sample_data_logs
| STATS average_bytes = AVG(bytes)

To build the chart:

1. Create an ES|QL visualization and run the query.
2. Set the visualization type to Gauge.
3. Assign average_bytes to the Metric dimension.
4. Set value ranges that give the metric context.
5. Customize the chart appearance using the gauge chart settings.
6. Select Apply and close.

The chart preview shows where the average number of bytes falls within the configured ranges.

After building the chart with the point-and-click editor or an ES|QL query, customize its appearance for your data and audience:

Set meaningful bounds

Define the minimum and maximum values that make sense for your metric. A CPU usage gauge should range from 0 to 100, while a sales target might range from 0 to your quarterly goal.

Use color bands for thresholds

Configure color ranges to indicate performance levels. Use green for acceptable values, yellow for warning, and red for critical thresholds.

Choose the right shape

Select a gauge shape that fits your dashboard layout. Use Arc shapes for traditional gauge appearance, or Linear for a more compact horizontal or vertical display.

Add context with titles

Provide clear titles that explain what the gauge measures and what the target value represents.

Refer to Gauge chart settings for all gauge chart configuration options. For panel sizing and layout guidance, refer to Organize dashboard panels.

Use a gauge to track progress toward a specific target, such as monthly sales goals or project completion percentage.

1. Create a Gauge chart and select your data view.
2. Configure the Metric dimension with your progress value (for example, Sum(sales_amount)).
3. Configure the Minimum value dimension as a static value of 0.
4. Configure the Maximum value dimension as a static value matching your target (for example, 100000 for a $100K sales goal).
5. Configure the Goal dimension as a static value matching your target to display a goal marker on the gauge.
6. Select the Metric dimension, enable Band colors, and configure Color mapping with bands to show progress levels.

POST kbn://api/visualizations
{
  "type": "gauge",
  "title": "Yearly sales goal",
  "filters": [],
  "query": { "expression": "" },
  "styling": {
    "shape": { "type": "bullet", "orientation": "horizontal" }
  },
  "metric": {
    "operation": "sum",
    "field": "products.taxful_price",
    "empty_as_null": true,
    "label": "Yearly sales",
    "max": { "operation": "static_value", "value": 1500000 },
    "goal": { "operation": "static_value", "value": 1000000 },
    "title": { "visible": true },
    "ticks": { "visible": true, "mode": "bands" },
    "color": {
      "type": "dynamic",
      "range": "absolute",
      "steps": [
        { "gte": 0, "lt": 750000, "color": "#f6726a" },
        { "gte": 750000, "lt": 1000000, "color": "#aee8d2" },
        { "gte": 1000000, "color": "#24c292" }
      ]
    }
  },
  "data_source": {
    "type": "data_view_spec",
    "index_pattern": "kibana_sample_data_ecommerce",
    "time_field": "order_date"
  }
}

curl -X POST "${KIBANA_URL}/api/visualizations" \
  -H "Authorization: ApiKey ${API_KEY}" \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "gauge",
  "title": "Yearly sales goal",
  "filters": [],
  "query": { "expression": "" },
  "styling": {
    "shape": { "type": "bullet", "orientation": "horizontal" }
  },
  "metric": {
    "operation": "sum",
    "field": "products.taxful_price",
    "empty_as_null": true,
    "label": "Yearly sales",
    "max": { "operation": "static_value", "value": 1500000 },
    "goal": { "operation": "static_value", "value": 1000000 },
    "title": { "visible": true },
    "ticks": { "visible": true, "mode": "bands" },
    "color": {
      "type": "dynamic",
      "range": "absolute",
      "steps": [
        { "gte": 0, "lt": 750000, "color": "#f6726a" },
        { "gte": 750000, "lt": 1000000, "color": "#aee8d2" },
        { "gte": 1000000, "color": "#24c292" }
      ]
    }
  },
  "data_source": {
    "type": "data_view_spec",
    "index_pattern": "kibana_sample_data_ecommerce",
    "time_field": "order_date"
  }
}'

Color bands help users quickly understand whether a value is within acceptable ranges.

1. Create a Gauge chart with your metric configured.
2. Select the Metric dimension to open its settings.
3. Enable Band colors.
4. In Color mapping, select a color palette (or use the default Status palette) and adjust the band boundaries and colors.
5. Optionally, enable Ticks on bands to display tick marks at the band boundaries on the gauge scale.

This example shows a gauge with server response time and color-coded health indicators.

POST kbn://api/visualizations
{
  "type": "gauge",
  "title": "Server response time",
  "filters": [],
  "query": { "expression": "" },
  "styling": { "shape": { "type": "bullet", "orientation": "horizontal" } },
  "metric": {
    "operation": "median",
    "field": "memory",
    "label": "Average response time - last hour",
    "format": { "type": "duration", "from": "us", "to": "ms" },
    "min": { "operation": "static_value", "value": 0 },
    "max": { "operation": "formula", "formula": "1000000" },
    "title": { "visible": true },
    "ticks": { "visible": true, "mode": "bands" },
    "color": {
      "type": "dynamic",
      "range": "absolute",
      "steps": [
        { "color": "#24c292", "gte": 0, "lt": 200000 },
        { "color": "#aee8d2", "gte": 200000, "lt": 500000 },
        { "color": "#f6726a", "gte": 500000 }
      ]
    }
  },
  "data_source": {
    "type": "data_view_spec",
    "index_pattern": "kibana_sample_data_logs",
    "time_field": "timestamp"
  }
}

curl -X POST "${KIBANA_URL}/api/visualizations" \
  -H "Authorization: ApiKey ${API_KEY}" \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "gauge",
  "title": "Server response time",
  "filters": [],
  "query": { "expression": "" },
  "styling": { "shape": { "type": "bullet", "orientation": "horizontal" } },
  "metric": {
    "operation": "median",
    "field": "memory",
    "label": "Average response time - last hour",
    "format": { "type": "duration", "from": "us", "to": "ms" },
    "min": { "operation": "static_value", "value": 0 },
    "max": { "operation": "formula", "formula": "1000000" },
    "title": { "visible": true },
    "ticks": { "visible": true, "mode": "bands" },
    "color": {
      "type": "dynamic",
      "range": "absolute",
      "steps": [
        { "color": "#24c292", "gte": 0, "lt": 200000 },
        { "color": "#aee8d2", "gte": 200000, "lt": 500000 },
        { "color": "#f6726a", "gte": 500000 }
      ]
    }
  },
  "data_source": {
    "type": "data_view_spec",
    "index_pattern": "kibana_sample_data_logs",
    "time_field": "timestamp"
  }
}'

Instead of entering fixed static values, you can use fields from your data to set the minimum, maximum, or goal dynamically using aggregations.

1. Create a Gauge chart with your metric configured.
2. In the Maximum value dimension, select a field and aggregation that represents the upper bound (for example, Max(quota) for a quota-based gauge).
3. Optionally, do the same for Minimum value (for example, Min(baseline)) or Goal (for example, Average(target)).

This approach is useful when bounds or targets vary by category, time period, or user. You can also use formulas to define dynamic bounds or goals. Refer to Lens formulas for more details.

Customize your gauge chart to display exactly the information you need, formatted the way you want.

The Metric dimension defines the main value displayed on the gauge.

Data

The value that the gauge displays. When you drag a field onto the chart, Kibana suggests a function based on the field type. You can use aggregation functions like Sum, Average, Count, Median, Last value, and more, or create custom calculations with formulas.

Advanced settings

Depending on the data you defined, several options allow you to apply additional filtering to the data taken into account to compute the final value to show.

Based on the type of visualization you're creating, only some of the following options can be available:

• Normalize by unit: Normalize the metric values to show per unit of time.
• Filter by: Specify a query.
• Reduced time range: Reduce the time range specified on the dashboard's time filter by the specified duration.
• Time shift: Shift the time range by the specified duration. This is useful if the value should use a different time range than the one selected on the dashboard.
• Hide zero values: Don't show values equal to zero. This option is on by default.

Appearance

• Name: Customize the metric label displayed in the gauge.
• Value format: Control how numeric values are displayed (number, percent, bytes, and more).
• Band colors: Toggle to enable colored bands on the gauge. When enabled, the following options appear:
  • Color mapping: Configure the color palette and define color stops for the bands. The default palette is Status with 4 color steps.
  • Ticks on bands: Toggle to place tick marks at band boundaries instead of distributing them evenly along the gauge scale.

The Minimum value dimension defines the lower bound of the gauge range.

Data

Set a static value, use a field with an aggregation like Min, or create a custom calculation with a formula. When adding this dimension, you can enter a fixed number directly (static value) or select a field to compute the minimum dynamically. If not configured, the gauge infers a minimum from the data.

Advanced settings

Depending on the data you defined, several options allow you to apply additional filtering to the data taken into account to compute the final value to show.

Based on the type of visualization you're creating, only some of the following options can be available:

• Normalize by unit: Normalize the metric values to show per unit of time.
• Filter by: Specify a query.
• Reduced time range: Reduce the time range specified on the dashboard's time filter by the specified duration.
• Time shift: Shift the time range by the specified duration. This is useful if the value should use a different time range than the one selected on the dashboard.
• Hide zero values: Don't show values equal to zero. This option is on by default.

Note

The minimum value must be less than the maximum value. If the minimum is greater than or equal to the maximum, the gauge displays an error.

Appearance

• Name: Customize the label for the minimum value.

The Maximum value dimension defines the upper bound of the gauge range.

Data

Set a static value, use a field with an aggregation like Max, or create a custom calculation with a formula. When adding this dimension, you can enter a fixed number directly (static value) or select a field to compute the maximum dynamically. If not configured, the gauge infers a maximum from the data.

Advanced settings

Depending on the data you defined, several options allow you to apply additional filtering to the data taken into account to compute the final value to show.

Based on the type of visualization you're creating, only some of the following options can be available:

• Normalize by unit: Normalize the metric values to show per unit of time.
• Filter by: Specify a query.
• Reduced time range: Reduce the time range specified on the dashboard's time filter by the specified duration.
• Time shift: Shift the time range by the specified duration. This is useful if the value should use a different time range than the one selected on the dashboard.
• Hide zero values: Don't show values equal to zero. This option is on by default.

Appearance

• Name: Customize the label for the maximum value.

The Goal dimension displays a target marker on the gauge, providing a visual reference point for the metric value.

Data

Set a static value, use a field with an aggregation, or create a custom calculation with a formula. When adding this dimension, you can enter a fixed number directly (static value) or select a field to compute the goal dynamically. The goal marker appears as a line or indicator on the gauge scale.

Advanced settings

Depending on the data you defined, several options allow you to apply additional filtering to the data taken into account to compute the final value to show.

Based on the type of visualization you're creating, only some of the following options can be available:

• Normalize by unit: Normalize the metric values to show per unit of time.
• Filter by: Specify a query.
• Reduced time range: Reduce the time range specified on the dashboard's time filter by the specified duration.
• Time shift: Shift the time range by the specified duration. This is useful if the value should use a different time range than the one selected on the dashboard.
• Hide zero values: Don't show values equal to zero. This option is on by default.

Appearance

• Name: Customize the label for the goal value.

When creating or editing a visualization, you can customize several appearance options from the Style menu.

Shape

Choose the gauge shape:

• Linear: A bar gauge, displayed horizontally (default) or vertically. Select Horizontal or Vertical orientation after choosing this shape.
• Minor arc: A partial circle arc.
• Major arc: A larger circular arc.
• Circle: A full 360-degree gauge.

Titles and text

Title

Control the gauge title:

• Auto: Display the metric name automatically (default).
• Custom: Enter a custom title.
• None: Hide the title.

Subtitle

Add an optional subtitle for additional context:

• Custom: Enter a custom subtitle.
• None: No subtitle (default).

The following examples show various configuration options for building impactful gauge charts.

CPU usage monitoring

Monitor system CPU usage with threshold-based coloring:

• Example based on: Kibana Sample Data Logs
• Metric: Formula average(machine.ram)/20000000000 formatted as percent
• Maximum: Formula max(machine.ram)/32211000000
• Shape: Semi-circle
• Color bands: 0–50% (green), 50–75% (yellow), 75%+ (red)

POST kbn://api/visualizations
{
  "type": "gauge",
  "title": "CPU usage",
  "filters": [],
  "query": { "expression": "" },
  "styling": { "shape": { "type": "semi_circle" } },
  "metric": {
    "operation": "formula",
    "formula": "average(machine.ram)/20000000000",
    "label": "CPU usage",
    "format": { "type": "percent", "decimals": 2, "compact": false },
    "max": { "operation": "formula", "formula": "max(machine.ram)/32211000000" },
    "title": { "visible": true },
    "ticks": { "visible": true, "mode": "bands" },
    "color": {
      "type": "dynamic",
      "range": "percentage",
      "steps": [
        { "gte": 0, "lt": 50, "color": "#24c292" },
        { "gte": 50, "lt": 75, "color": "#EAAE01" },
        { "gte": 75, "color": "#f6726a" }
      ]
    }
  },
  "data_source": {
    "type": "data_view_spec",
    "index_pattern": "kibana_sample_data_logs",
    "time_field": "timestamp"
  }
}

curl -X POST "${KIBANA_URL}/api/visualizations" \
  -H "Authorization: ApiKey ${API_KEY}" \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "gauge",
  "title": "CPU usage",
  "filters": [],
  "query": { "expression": "" },
  "styling": { "shape": { "type": "semi_circle" } },
  "metric": {
    "operation": "formula",
    "formula": "average(machine.ram)/20000000000",
    "label": "CPU usage",
    "format": { "type": "percent", "decimals": 2, "compact": false },
    "max": { "operation": "formula", "formula": "max(machine.ram)/32211000000" },
    "title": { "visible": true },
    "ticks": { "visible": true, "mode": "bands" },
    "color": {
      "type": "dynamic",
      "range": "percentage",
      "steps": [
        { "gte": 0, "lt": 50, "color": "#24c292" },
        { "gte": 50, "lt": 75, "color": "#EAAE01" },
        { "gte": 75, "color": "#f6726a" }
      ]
    }
  },
  "data_source": {
    "type": "data_view_spec",
    "index_pattern": "kibana_sample_data_logs",
    "time_field": "timestamp"
  }
}'

Disk space utilization

Display disk space usage as a percentage of capacity:

• Example based on: Kibana Sample Data Logs
• Metric: Formula average(machine.ram)/29000000000 formatted as percent
• Maximum: Formula max(machine.ram)/32211000000
• Shape: Circle
• Color bands: 0–60% (green), 60–80% (yellow), 80%+ (red)

POST kbn://api/visualizations
{
  "type": "gauge",
  "title": "Disk space utilization",
  "filters": [],
  "query": { "expression": "" },
  "styling": {
    "shape": { "type": "circle" }
  },
  "metric": {
    "operation": "formula",
    "formula": "average(machine.ram)/29000000000",
    "label": "Disk space utilization",
    "format": { "type": "percent", "decimals": 2, "compact": false },
    "max": { "operation": "formula", "formula": "max(machine.ram)/32211000000" },
    "title": { "visible": true },
    "ticks": { "visible": true, "mode": "bands" },
    "color": {
      "type": "dynamic",
      "range": "percentage",
      "steps": [
        { "gte": 0, "lt": 60, "color": "#24c292" },
        { "gte": 60, "lt": 80, "color": "#EAAE01" },
        { "gte": 80, "color": "#f6726a" }
      ]
    }
  },
  "data_source": {
    "type": "data_view_spec",
    "index_pattern": "kibana_sample_data_logs",
    "time_field": "timestamp"
  }
}

curl -X POST "${KIBANA_URL}/api/visualizations" \
  -H "Authorization: ApiKey ${API_KEY}" \
  -H "kbn-xsrf: true" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "gauge",
  "title": "Disk space utilization",
  "filters": [],
  "query": { "expression": "" },
  "styling": {
    "shape": { "type": "circle" }
  },
  "metric": {
    "operation": "formula",
    "formula": "average(machine.ram)/29000000000",
    "label": "Disk space utilization",
    "format": { "type": "percent", "decimals": 2, "compact": false },
    "max": { "operation": "formula", "formula": "max(machine.ram)/32211000000" },
    "title": { "visible": true },
    "ticks": { "visible": true, "mode": "bands" },
    "color": {
      "type": "dynamic",
      "range": "percentage",
      "steps": [
        { "gte": 0, "lt": 60, "color": "#24c292" },
        { "gte": 60, "lt": 80, "color": "#EAAE01" },
        { "gte": 80, "color": "#f6726a" }
      ]
    }
  },
  "data_source": {
    "type": "data_view_spec",
    "index_pattern": "kibana_sample_data_logs",
    "time_field": "timestamp"
  }
}'