Gauge Chart Panel Configuration¶
The Gauge chart panel displays a single metric value with optional min/max ranges and goal indicators, typically used for KPIs and progress tracking toward targets or thresholds.
A Poem for the Progress Trackers¶
For those who measure how close we are to the goal:
Not just a number on the screen,
But progress toward a target seen.
A gauge that fills from left to right,
From zero darkness into light.
Where are we now? How far to go?
The gauge will always let you know.
From minimum to maximum range,
Watch the colored needle change.
A goal line drawn across the way—
"You're almost there!" the markers say.
Arc or bullet, circle or bar:
The gauge reveals just where you are.
CPU usage, quota met,
Performance targets? Not a sweat.
Not just data, but direction clear—
The gauge tracks progress throughout the year.
Lens Gauge Charts¶
Represents a Gauge chart configuration within a Lens panel.
Gauge charts display a single metric value with optional min/max ranges and goal indicators, typically used to show progress toward a target or threshold.
Examples:
Minimal gauge with static values:
lens:
type: gauge
data_view: "metrics-*"
metric:
aggregation: average
field: system.cpu.total.pct
minimum: 0
maximum: 100
goal: 80
Gauge with custom appearance and color:
lens:
type: gauge
data_view: "logs-*"
metric:
aggregation: average
field: response_time_ms
minimum: 0
maximum: 1000
goal: 500
color:
range_type: percent
thresholds:
- up_to: 0
color: "#00BF6F"
- up_to: 80
color: "#FFA500"
appearance:
shape: arc
Attributes:
| Name | Type | Description |
|---|---|---|
data_view |
str
|
The data view that determines the data for the gauge chart. |
metric |
LensDataMetricTypes
|
The primary metric to display in the gauge. This is the main value shown. |
minimum |
LensMetricTypes | int | float | None
|
An optional minimum value for the gauge range. Can be a metric (field-based) or a static numeric value. |
maximum |
LensMetricTypes | int | float | None
|
An optional maximum value for the gauge range. Can be a metric (field-based) or a static numeric value. |
goal |
LensMetricTypes | int | float | None
|
An optional goal/target value to display as a reference. Can be a metric (field-based) or a static numeric value. |
Show JSON schema:
{
"$defs": {
"ColorRangeMapping": {
"additionalProperties": false,
"description": "Range/threshold-based color mapping for numeric values.",
"properties": {
"range_type": {
"default": "number",
"description": "How threshold values are interpreted by Kibana.",
"enum": [
"number",
"percent"
],
"title": "Range Type",
"type": "string"
},
"range_min": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": 0,
"description": "Optional lower bound for the palette domain. Use null for auto/open lower bound.",
"title": "Range Min"
},
"range_max": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional upper bound for the palette domain. Use null for auto/open upper bound.",
"title": "Range Max"
},
"thresholds": {
"description": "Ordered threshold bands used to build gauge-style color palettes.",
"items": {
"$ref": "#/$defs/ColorThreshold"
},
"minItems": 1,
"title": "Thresholds",
"type": "array"
}
},
"required": [
"thresholds"
],
"title": "ColorRangeMapping",
"type": "object"
},
"ColorThreshold": {
"additionalProperties": false,
"description": "Single threshold band in a range-based color map.",
"properties": {
"up_to": {
"description": "Upper bound for this threshold band.",
"title": "Up To",
"type": "number"
},
"color": {
"description": "The color applied within this threshold band (hex color code).",
"title": "Color",
"type": "string"
}
},
"required": [
"up_to",
"color"
],
"title": "ColorThreshold",
"type": "object"
},
"GaugeAppearance": {
"additionalProperties": false,
"description": "Appearance configuration for gauge visualizations.\n\nGroups all visual styling options for gauge charts including shape, tick positioning,\nand label configuration.",
"properties": {
"shape": {
"anyOf": [
{
"enum": [
"horizontal_bullet",
"vertical_bullet",
"arc",
"circle",
"semi_circle"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The shape of the gauge visualization.",
"title": "Shape"
},
"ticks_position": {
"anyOf": [
{
"enum": [
"auto",
"bands",
"hidden"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Position of tick marks on the gauge.",
"title": "Ticks Position"
},
"label_major": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Major label text to display on the gauge.",
"title": "Label Major"
},
"label_minor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Minor label text to display on the gauge.",
"title": "Label Minor"
}
},
"title": "GaugeAppearance",
"type": "object"
},
"GaugeTitlesAndText": {
"additionalProperties": false,
"description": "Title and subtitle display options for gauges.\n\nThese fields map to Kibana gauge `labelMajor` (title) and `labelMinor` (subtitle).\n\n- ``None`` (omit): Kibana default (auto for title, hidden for subtitle)\n- ``False``: explicitly hidden\n- ``str``: custom text",
"properties": {
"title": {
"anyOf": [
{
"type": "string"
},
{
"const": false,
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Gauge title. Omit for Kibana default, ``False`` to hide, or a string for custom text.",
"title": "Title"
},
"subtitle": {
"anyOf": [
{
"type": "string"
},
{
"const": false,
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Gauge subtitle. Omit for no subtitle, ``False`` to hide, or a string for custom text.",
"title": "Subtitle"
}
},
"title": "GaugeTitlesAndText",
"type": "object"
},
"KqlQuery": {
"additionalProperties": false,
"description": "Represents a KQL (Kibana Query Language) query configuration.\n\nKQL is the default query language in Kibana and provides a simplified syntax for filtering data.",
"properties": {
"kql": {
"description": "The Kibana Query Language (KQL) query string to apply.",
"title": "Kql",
"type": "string"
}
},
"required": [
"kql"
],
"title": "KqlQuery",
"type": "object"
},
"LegacyQueryTypes": {
"oneOf": [
{
"$ref": "#/$defs/KqlQuery"
},
{
"$ref": "#/$defs/LuceneQuery"
}
]
},
"LensAggregatedMetricTypes": {
"anyOf": [
{
"$ref": "#/$defs/LensOtherAggregatedMetric"
},
{
"$ref": "#/$defs/LensLastValueAggregatedMetric"
},
{
"$ref": "#/$defs/LensCountAggregatedMetric"
},
{
"$ref": "#/$defs/LensSumAggregatedMetric"
},
{
"$ref": "#/$defs/LensPercentileRankAggregatedMetric"
},
{
"$ref": "#/$defs/LensPercentileAggregatedMetric"
}
]
},
"LensCountAggregatedMetric": {
"additionalProperties": false,
"description": "Represents a count metric configuration within a Lens chart.\n\nCount metrics are used to count the number of documents in a data view.",
"properties": {
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "A unique identifier. If not provided, one will be generated automatically.",
"title": "Id"
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The display label for the metric. If not provided, a label may be inferred from the type and field.",
"title": "Label"
},
"format": {
"anyOf": [
{
"$ref": "#/$defs/LensMetricFormatTypes"
},
{
"type": "null"
}
],
"default": null,
"description": "The format of the metric."
},
"filter": {
"anyOf": [
{
"$ref": "#/$defs/LegacyQueryTypes"
},
{
"type": "null"
}
],
"default": null,
"description": "A KQL filter applied before determining the metric value."
},
"aggregation": {
"default": "count",
"enum": [
"count",
"unique_count"
],
"title": "Aggregation",
"type": "string"
},
"field": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The field to count. If not provided, the count will be of all documents in the data view.",
"title": "Field"
},
"exclude_zeros": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether to exclude zero values from the count. Kibana defaults to true if not specified.",
"title": "Exclude Zeros"
}
},
"title": "LensCountAggregatedMetric",
"type": "object"
},
"LensCustomMetricFormat": {
"additionalProperties": false,
"description": "Custom format configuration for metrics using numeral.js patterns.\n\nUse this for complete control over numeric formatting with numeral.js syntax.",
"properties": {
"type": {
"const": "custom",
"default": "custom",
"description": "Format type identifier. Must be 'custom' for custom formats.",
"title": "Type",
"type": "string"
},
"decimals": {
"anyOf": [
{
"minimum": 0,
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "The number of decimal places to display. If not specified, defaults to 0.",
"title": "Decimals"
},
"pattern": {
"description": "numeral.js format pattern (e.g., \"0,0.00\" for comma-separated numbers with 2 decimals).",
"title": "Pattern",
"type": "string"
},
"suffix": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional suffix to display after the formatted number (e.g., \" requests\", \" users\").",
"title": "Suffix"
},
"compact": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether to use compact notation (e.g., 1.2K instead of 1200). Defaults to Kibana's behavior.",
"title": "Compact"
}
},
"required": [
"pattern"
],
"title": "LensCustomMetricFormat",
"type": "object"
},
"LensDataMetricTypes": {
"anyOf": [
{
"$ref": "#/$defs/LensFormulaMetric"
},
{
"$ref": "#/$defs/LensAggregatedMetricTypes"
}
]
},
"LensFormulaMetric": {
"additionalProperties": false,
"description": "Represents a formula metric configuration within a Lens chart.\n\nFormula metrics allow for custom calculations using Kibana's formula syntax.\nThe formula string is passed directly to Kibana, which handles parsing and\nAST generation internally.\n\nExample formulas:\n- Simple arithmetic: \"count() / 100\"\n- Field aggregations: \"(max(response.time) - min(response.time)) / average(response.time)\"\n- With filters: \"count(kql='status:error') / count() * 100\"",
"properties": {
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "A unique identifier. If not provided, one will be generated automatically.",
"title": "Id"
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The display label for the metric. If not provided, a label may be inferred from the type and field.",
"title": "Label"
},
"format": {
"anyOf": [
{
"$ref": "#/$defs/LensMetricFormatTypes"
},
{
"type": "null"
}
],
"default": null,
"description": "The format of the metric."
},
"filter": {
"anyOf": [
{
"$ref": "#/$defs/LegacyQueryTypes"
},
{
"type": "null"
}
],
"default": null,
"description": "A KQL filter applied before determining the metric value."
},
"formula": {
"description": "The formula string to be evaluated for this metric.",
"title": "Formula",
"type": "string"
}
},
"required": [
"formula"
],
"title": "LensFormulaMetric",
"type": "object"
},
"LensLastValueAggregatedMetric": {
"additionalProperties": false,
"description": "Represents a last value metric configuration within a Lens chart.\n\nLast value metrics are used to retrieve the most recent value of a field based on a specified sort order.",
"properties": {
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "A unique identifier. If not provided, one will be generated automatically.",
"title": "Id"
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The display label for the metric. If not provided, a label may be inferred from the type and field.",
"title": "Label"
},
"format": {
"anyOf": [
{
"$ref": "#/$defs/LensMetricFormatTypes"
},
{
"type": "null"
}
],
"default": null,
"description": "The format of the metric."
},
"filter": {
"anyOf": [
{
"$ref": "#/$defs/LegacyQueryTypes"
},
{
"type": "null"
}
],
"default": null,
"description": "A KQL filter applied before determining the metric value."
},
"aggregation": {
"const": "last_value",
"default": "last_value",
"title": "Aggregation",
"type": "string"
},
"field": {
"title": "Field",
"type": "string"
},
"date_field": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The field used to determine the 'last' value.",
"title": "Date Field"
}
},
"required": [
"field"
],
"title": "LensLastValueAggregatedMetric",
"type": "object"
},
"LensMetricFormat": {
"additionalProperties": false,
"description": "Standard format configuration for displaying metric values.\n\nSupports common numeric formats with optional suffix and compact notation.",
"properties": {
"type": {
"description": "The format type for the metric value.\n\nAvailable formats:\n- **number**: Plain numeric value with optional decimal places\n- **bytes**: Byte size formatting (B, KB, MB, GB, TB)\n- **bits**: Bit size formatting (b, Kb, Mb, Gb, Tb)\n- **percent**: Percentage formatting with % symbol\n- **duration**: Time duration formatting (ms, s, m, h, d)",
"enum": [
"number",
"bytes",
"bits",
"percent",
"duration"
],
"title": "Type",
"type": "string"
},
"decimals": {
"anyOf": [
{
"minimum": 0,
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "The number of decimal places to display. If not specified, defaults to 2 for number/bytes/percent, 0 for bits/duration.",
"title": "Decimals"
},
"suffix": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional suffix to display after the formatted number (e.g., \" requests\", \" users\").",
"title": "Suffix"
},
"compact": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether to use compact notation (e.g., 1.2K instead of 1200). Defaults to Kibana's behavior.",
"title": "Compact"
}
},
"required": [
"type"
],
"title": "LensMetricFormat",
"type": "object"
},
"LensMetricFormatTypes": {
"anyOf": [
{
"$ref": "#/$defs/LensMetricFormat"
},
{
"$ref": "#/$defs/LensCustomMetricFormat"
}
]
},
"LensMetricTypes": {
"anyOf": [
{
"$ref": "#/$defs/LensFormulaMetric"
},
{
"$ref": "#/$defs/LensAggregatedMetricTypes"
},
{
"$ref": "#/$defs/LensStaticValue"
}
]
},
"LensOtherAggregatedMetric": {
"additionalProperties": false,
"description": "Represents various aggregated metric configurations within a Lens chart.",
"properties": {
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "A unique identifier. If not provided, one will be generated automatically.",
"title": "Id"
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The display label for the metric. If not provided, a label may be inferred from the type and field.",
"title": "Label"
},
"format": {
"anyOf": [
{
"$ref": "#/$defs/LensMetricFormatTypes"
},
{
"type": "null"
}
],
"default": null,
"description": "The format of the metric."
},
"filter": {
"anyOf": [
{
"$ref": "#/$defs/LegacyQueryTypes"
},
{
"type": "null"
}
],
"default": null,
"description": "A KQL filter applied before determining the metric value."
},
"aggregation": {
"description": "The aggregation type for the metric (e.g., 'min', 'max', 'median', 'average', 'standard_deviation').",
"enum": [
"min",
"max",
"median",
"average",
"standard_deviation"
],
"title": "Aggregation",
"type": "string"
},
"field": {
"title": "Field",
"type": "string"
}
},
"required": [
"aggregation",
"field"
],
"title": "LensOtherAggregatedMetric",
"type": "object"
},
"LensPercentileAggregatedMetric": {
"additionalProperties": false,
"description": "Represents a percentile metric configuration within a Lens chart.\n\nPercentile metrics are used to determine the value at a specific percentile in a data set.",
"properties": {
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "A unique identifier. If not provided, one will be generated automatically.",
"title": "Id"
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The display label for the metric. If not provided, a label may be inferred from the type and field.",
"title": "Label"
},
"format": {
"anyOf": [
{
"$ref": "#/$defs/LensMetricFormatTypes"
},
{
"type": "null"
}
],
"default": null,
"description": "The format of the metric."
},
"filter": {
"anyOf": [
{
"$ref": "#/$defs/LegacyQueryTypes"
},
{
"type": "null"
}
],
"default": null,
"description": "A KQL filter applied before determining the metric value."
},
"aggregation": {
"const": "percentile",
"default": "percentile",
"title": "Aggregation",
"type": "string"
},
"field": {
"title": "Field",
"type": "string"
},
"percentile": {
"title": "Percentile",
"type": "integer"
}
},
"required": [
"field",
"percentile"
],
"title": "LensPercentileAggregatedMetric",
"type": "object"
},
"LensPercentileRankAggregatedMetric": {
"additionalProperties": false,
"description": "Represents a percentile rank metric configuration within a Lens chart.\n\nPercentile rank metrics are used to determine the rank of a value in a data set.",
"properties": {
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "A unique identifier. If not provided, one will be generated automatically.",
"title": "Id"
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The display label for the metric. If not provided, a label may be inferred from the type and field.",
"title": "Label"
},
"format": {
"anyOf": [
{
"$ref": "#/$defs/LensMetricFormatTypes"
},
{
"type": "null"
}
],
"default": null,
"description": "The format of the metric."
},
"filter": {
"anyOf": [
{
"$ref": "#/$defs/LegacyQueryTypes"
},
{
"type": "null"
}
],
"default": null,
"description": "A KQL filter applied before determining the metric value."
},
"aggregation": {
"const": "percentile_rank",
"default": "percentile_rank",
"title": "Aggregation",
"type": "string"
},
"field": {
"title": "Field",
"type": "string"
},
"rank": {
"title": "Rank",
"type": "integer"
}
},
"required": [
"field",
"rank"
],
"title": "LensPercentileRankAggregatedMetric",
"type": "object"
},
"LensStaticValue": {
"additionalProperties": false,
"description": "Represents a static numeric value metric in Lens charts.\n\nUsed to display a fixed numeric value rather than aggregating from data.\nCommonly used for gauge min/max/goal values or reference lines.",
"properties": {
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "A unique identifier. If not provided, one will be generated automatically.",
"title": "Id"
},
"value": {
"anyOf": [
{
"type": "integer"
},
{
"type": "number"
}
],
"description": "The static numeric value to display.",
"title": "Value"
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional label for the static value.",
"title": "Label"
}
},
"required": [
"value"
],
"title": "LensStaticValue",
"type": "object"
},
"LensSumAggregatedMetric": {
"additionalProperties": false,
"description": "Represents a sum metric configuration within a Lens chart.\n\nSum metrics are used to sum the values of a field.",
"properties": {
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "A unique identifier. If not provided, one will be generated automatically.",
"title": "Id"
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The display label for the metric. If not provided, a label may be inferred from the type and field.",
"title": "Label"
},
"format": {
"anyOf": [
{
"$ref": "#/$defs/LensMetricFormatTypes"
},
{
"type": "null"
}
],
"default": null,
"description": "The format of the metric."
},
"filter": {
"anyOf": [
{
"$ref": "#/$defs/LegacyQueryTypes"
},
{
"type": "null"
}
],
"default": null,
"description": "A KQL filter applied before determining the metric value."
},
"aggregation": {
"const": "sum",
"default": "sum",
"title": "Aggregation",
"type": "string"
},
"field": {
"title": "Field",
"type": "string"
},
"exclude_zeros": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether to exclude zero values from the sum. Kibana defaults to true if not specified.",
"title": "Exclude Zeros"
}
},
"required": [
"field"
],
"title": "LensSumAggregatedMetric",
"type": "object"
},
"LuceneQuery": {
"additionalProperties": false,
"description": "Represents a Lucene query configuration.\n\nLucene provides a more powerful and flexible, but less friendly, syntax for querying data compared to KQL.",
"properties": {
"lucene": {
"description": "The Lucene query string to apply.",
"title": "Lucene",
"type": "string"
}
},
"required": [
"lucene"
],
"title": "LuceneQuery",
"type": "object"
}
},
"additionalProperties": false,
"description": "Represents a Gauge chart configuration within a Lens panel.\n\nGauge charts display a single metric value with optional min/max ranges and goal indicators,\ntypically used to show progress toward a target or threshold.\n\nExamples:\n Minimal gauge with static values:\n ```yaml\n lens:\n type: gauge\n data_view: \"metrics-*\"\n metric:\n aggregation: average\n field: system.cpu.total.pct\n minimum: 0\n maximum: 100\n goal: 80\n ```\n\n Gauge with custom appearance and color:\n ```yaml\n lens:\n type: gauge\n data_view: \"logs-*\"\n metric:\n aggregation: average\n field: response_time_ms\n minimum: 0\n maximum: 1000\n goal: 500\n color:\n range_type: percent\n thresholds:\n - up_to: 0\n color: \"#00BF6F\"\n - up_to: 80\n color: \"#FFA500\"\n appearance:\n shape: arc\n ```",
"properties": {
"type": {
"const": "gauge",
"default": "gauge",
"description": "The type of chart, which is 'gauge' for this visualization.",
"title": "Type",
"type": "string"
},
"color": {
"anyOf": [
{
"$ref": "#/$defs/ColorRangeMapping"
},
{
"type": "null"
}
],
"default": null,
"description": "Range-based palette configuration for gauge thresholds. When set, enables palette color mode."
},
"appearance": {
"anyOf": [
{
"$ref": "#/$defs/GaugeAppearance"
},
{
"type": "null"
}
],
"default": null,
"description": "Visual appearance configuration for the gauge."
},
"titles_and_text": {
"anyOf": [
{
"$ref": "#/$defs/GaugeTitlesAndText"
},
{
"type": "null"
}
],
"default": null,
"description": "Title and subtitle options mapped to gauge `label_major` and `label_minor`."
},
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "A unique identifier. If not provided, one will be generated automatically.",
"title": "Id"
},
"data_view": {
"description": "The data view that determines the data for the gauge chart.",
"title": "Data View",
"type": "string"
},
"metric": {
"$ref": "#/$defs/LensDataMetricTypes",
"description": "The primary metric to display in the gauge. This is the main value shown."
},
"minimum": {
"anyOf": [
{
"$ref": "#/$defs/LensMetricTypes"
},
{
"type": "integer"
},
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "An optional minimum value for the gauge range. Can be a metric (field-based) or a static numeric value.",
"title": "Minimum"
},
"maximum": {
"anyOf": [
{
"$ref": "#/$defs/LensMetricTypes"
},
{
"type": "integer"
},
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "An optional maximum value for the gauge range. Can be a metric (field-based) or a static numeric value.",
"title": "Maximum"
},
"goal": {
"anyOf": [
{
"$ref": "#/$defs/LensMetricTypes"
},
{
"type": "integer"
},
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "An optional goal/target value to display as a reference. Can be a metric (field-based) or a static numeric value.",
"title": "Goal"
}
},
"required": [
"data_view",
"metric"
],
"title": "LensGaugeChart",
"type": "object"
}
Gauge Appearance¶
Appearance configuration for gauge visualizations.
Groups all visual styling options for gauge charts including shape, tick positioning, and label configuration.
Attributes:
| Name | Type | Description |
|---|---|---|
shape |
Literal['horizontal_bullet', 'vertical_bullet', 'arc', 'circle', 'semi_circle'] | None
|
The shape of the gauge visualization. |
ticks_position |
Literal['auto', 'bands', 'hidden'] | None
|
Position of tick marks on the gauge. |
label_major |
str | None
|
Major label text to display on the gauge. |
label_minor |
str | None
|
Minor label text to display on the gauge. |
Show JSON schema:
{
"additionalProperties": false,
"description": "Appearance configuration for gauge visualizations.\n\nGroups all visual styling options for gauge charts including shape, tick positioning,\nand label configuration.",
"properties": {
"shape": {
"anyOf": [
{
"enum": [
"horizontal_bullet",
"vertical_bullet",
"arc",
"circle",
"semi_circle"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The shape of the gauge visualization.",
"title": "Shape"
},
"ticks_position": {
"anyOf": [
{
"enum": [
"auto",
"bands",
"hidden"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Position of tick marks on the gauge.",
"title": "Ticks Position"
},
"label_major": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Major label text to display on the gauge.",
"title": "Label Major"
},
"label_minor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Minor label text to display on the gauge.",
"title": "Label Minor"
}
},
"title": "GaugeAppearance",
"type": "object"
}
ES|QL Gauge Charts¶
Represents a Gauge chart configuration within an ESQL panel.
Gauge charts display a single metric value with optional min/max ranges and goal indicators, typically used to show progress toward a target or threshold.
Examples:
ES|QL gauge with STATS query:
esql:
type: gauge
query: |
FROM metrics-*
| STATS avg_cpu = AVG(system.cpu.total.pct),
min_cpu = MIN(system.cpu.total.pct),
max_cpu = MAX(system.cpu.total.pct)
| EVAL goal_cpu = 80
metric:
field: "avg_cpu"
minimum:
field: "min_cpu"
maximum:
field: "max_cpu"
goal:
field: "goal_cpu"
appearance:
shape: arc
Attributes:
| Name | Type | Description |
|---|---|---|
metric |
ESQLMetric
|
The primary metric to display in the gauge. This is the main value shown. |
minimum |
ESQLMetric | None
|
An optional minimum value for the gauge range, referenced from an ESQL query field. |
maximum |
ESQLMetric | None
|
An optional maximum value for the gauge range, referenced from an ESQL query field. |
goal |
ESQLMetric | None
|
An optional goal/target value to display as a reference, referenced from an ESQL query field. |
Show JSON schema:
{
"$defs": {
"ColorRangeMapping": {
"additionalProperties": false,
"description": "Range/threshold-based color mapping for numeric values.",
"properties": {
"range_type": {
"default": "number",
"description": "How threshold values are interpreted by Kibana.",
"enum": [
"number",
"percent"
],
"title": "Range Type",
"type": "string"
},
"range_min": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": 0,
"description": "Optional lower bound for the palette domain. Use null for auto/open lower bound.",
"title": "Range Min"
},
"range_max": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional upper bound for the palette domain. Use null for auto/open upper bound.",
"title": "Range Max"
},
"thresholds": {
"description": "Ordered threshold bands used to build gauge-style color palettes.",
"items": {
"$ref": "#/$defs/ColorThreshold"
},
"minItems": 1,
"title": "Thresholds",
"type": "array"
}
},
"required": [
"thresholds"
],
"title": "ColorRangeMapping",
"type": "object"
},
"ColorThreshold": {
"additionalProperties": false,
"description": "Single threshold band in a range-based color map.",
"properties": {
"up_to": {
"description": "Upper bound for this threshold band.",
"title": "Up To",
"type": "number"
},
"color": {
"description": "The color applied within this threshold band (hex color code).",
"title": "Color",
"type": "string"
}
},
"required": [
"up_to",
"color"
],
"title": "ColorThreshold",
"type": "object"
},
"ESQLCustomMetricFormat": {
"additionalProperties": false,
"description": "Custom format configuration for ES|QL metrics.\n\nAllows specifying a custom number format pattern.\nThis is separate from LensCustomMetricFormat as ES|QL and Lens formatting may diverge in the future.",
"properties": {
"type": {
"const": "custom",
"default": "custom",
"title": "Type",
"type": "string"
},
"pattern": {
"description": "The pattern to display the number in.",
"title": "Pattern",
"type": "string"
}
},
"required": [
"pattern"
],
"title": "ESQLCustomMetricFormat",
"type": "object"
},
"ESQLMetric": {
"additionalProperties": false,
"description": "A metric that is defined in the ESQL query.",
"properties": {
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "A unique identifier. If not provided, one will be generated automatically.",
"title": "Id"
},
"field": {
"description": "The field in the data view that this metric is based on.",
"title": "Field",
"type": "string"
},
"label": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Optional display label for the metric.",
"title": "Label"
},
"format": {
"anyOf": [
{
"$ref": "#/$defs/ESQLMetricFormatTypes"
},
{
"type": "null"
}
],
"default": null,
"description": "The format of the metric (number, bytes, bits, percent, duration, or custom)."
}
},
"required": [
"field"
],
"title": "ESQLMetric",
"type": "object"
},
"ESQLMetricFormat": {
"additionalProperties": false,
"description": "The format configuration for ES|QL metrics.\n\nSupports standard format types like number, bytes, bits, percent, and duration.\nThis is separate from LensMetricFormat as ES|QL and Lens formatting may diverge in the future.",
"properties": {
"type": {
"enum": [
"number",
"bytes",
"bits",
"percent",
"duration"
],
"title": "Type",
"type": "string"
},
"decimals": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"default": null,
"description": "The number of decimal places to display. If not specified, defaults to 2 for number/bytes/percent/duration, 0 for bits.",
"title": "Decimals"
},
"suffix": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The suffix to display after the number.",
"title": "Suffix"
},
"compact": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Whether to display the number in a compact format.",
"title": "Compact"
},
"pattern": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The pattern to display the number in.",
"title": "Pattern"
}
},
"required": [
"type"
],
"title": "ESQLMetricFormat",
"type": "object"
},
"ESQLMetricFormatTypes": {
"anyOf": [
{
"$ref": "#/$defs/ESQLMetricFormat"
},
{
"$ref": "#/$defs/ESQLCustomMetricFormat"
}
]
},
"GaugeAppearance": {
"additionalProperties": false,
"description": "Appearance configuration for gauge visualizations.\n\nGroups all visual styling options for gauge charts including shape, tick positioning,\nand label configuration.",
"properties": {
"shape": {
"anyOf": [
{
"enum": [
"horizontal_bullet",
"vertical_bullet",
"arc",
"circle",
"semi_circle"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "The shape of the gauge visualization.",
"title": "Shape"
},
"ticks_position": {
"anyOf": [
{
"enum": [
"auto",
"bands",
"hidden"
],
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Position of tick marks on the gauge.",
"title": "Ticks Position"
},
"label_major": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Major label text to display on the gauge.",
"title": "Label Major"
},
"label_minor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "Minor label text to display on the gauge.",
"title": "Label Minor"
}
},
"title": "GaugeAppearance",
"type": "object"
},
"GaugeTitlesAndText": {
"additionalProperties": false,
"description": "Title and subtitle display options for gauges.\n\nThese fields map to Kibana gauge `labelMajor` (title) and `labelMinor` (subtitle).\n\n- ``None`` (omit): Kibana default (auto for title, hidden for subtitle)\n- ``False``: explicitly hidden\n- ``str``: custom text",
"properties": {
"title": {
"anyOf": [
{
"type": "string"
},
{
"const": false,
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Gauge title. Omit for Kibana default, ``False`` to hide, or a string for custom text.",
"title": "Title"
},
"subtitle": {
"anyOf": [
{
"type": "string"
},
{
"const": false,
"type": "boolean"
},
{
"type": "null"
}
],
"default": null,
"description": "Gauge subtitle. Omit for no subtitle, ``False`` to hide, or a string for custom text.",
"title": "Subtitle"
}
},
"title": "GaugeTitlesAndText",
"type": "object"
}
},
"additionalProperties": false,
"description": "Represents a Gauge chart configuration within an ESQL panel.\n\nGauge charts display a single metric value with optional min/max ranges and goal indicators,\ntypically used to show progress toward a target or threshold.\n\nExamples:\n ES|QL gauge with STATS query:\n ```yaml\n esql:\n type: gauge\n query: |\n FROM metrics-*\n | STATS avg_cpu = AVG(system.cpu.total.pct),\n min_cpu = MIN(system.cpu.total.pct),\n max_cpu = MAX(system.cpu.total.pct)\n | EVAL goal_cpu = 80\n metric:\n field: \"avg_cpu\"\n minimum:\n field: \"min_cpu\"\n maximum:\n field: \"max_cpu\"\n goal:\n field: \"goal_cpu\"\n appearance:\n shape: arc\n ```",
"properties": {
"type": {
"const": "gauge",
"default": "gauge",
"description": "The type of chart, which is 'gauge' for this visualization.",
"title": "Type",
"type": "string"
},
"color": {
"anyOf": [
{
"$ref": "#/$defs/ColorRangeMapping"
},
{
"type": "null"
}
],
"default": null,
"description": "Range-based palette configuration for gauge thresholds. When set, enables palette color mode."
},
"appearance": {
"anyOf": [
{
"$ref": "#/$defs/GaugeAppearance"
},
{
"type": "null"
}
],
"default": null,
"description": "Visual appearance configuration for the gauge."
},
"titles_and_text": {
"anyOf": [
{
"$ref": "#/$defs/GaugeTitlesAndText"
},
{
"type": "null"
}
],
"default": null,
"description": "Title and subtitle options mapped to gauge `label_major` and `label_minor`."
},
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"default": null,
"description": "A unique identifier. If not provided, one will be generated automatically.",
"title": "Id"
},
"metric": {
"$ref": "#/$defs/ESQLMetric",
"description": "The primary metric to display in the gauge. This is the main value shown."
},
"minimum": {
"anyOf": [
{
"$ref": "#/$defs/ESQLMetric"
},
{
"type": "null"
}
],
"default": null,
"description": "An optional minimum value for the gauge range, referenced from an ESQL query field."
},
"maximum": {
"anyOf": [
{
"$ref": "#/$defs/ESQLMetric"
},
{
"type": "null"
}
],
"default": null,
"description": "An optional maximum value for the gauge range, referenced from an ESQL query field."
},
"goal": {
"anyOf": [
{
"$ref": "#/$defs/ESQLMetric"
},
{
"type": "null"
}
],
"default": null,
"description": "An optional goal/target value to display as a reference, referenced from an ESQL query field."
}
},
"required": [
"metric"
],
"title": "ESQLGaugeChart",
"type": "object"
}