Lens Panel Configuration

Lens panels in Kibana provide a flexible and user-friendly way to create various types of visualizations, such as metric displays, pie charts, bar charts, line charts, and more. This document covers the YAML configuration for Lens panels using this compiler.

The LensPanel is the primary container. Its lens field contains the specific visualization configuration (for example metric, pie, line, or datatable).

A Poem for the Lens Pioneers

For those who craft visualizations with elegant flexibility:

Through this Lens we magnify
Patterns hiding oh so sly.
From metrics bold to pies that slice,
Lens makes your data look quite nice!

Dimensions group and metrics measure,
Aggregations are your treasure.
count(), sum(), and unique_count() too,
Percentiles show p95 to you.

Date histograms go back in time,
Top values sorted, so sublime.
Formulas for custom math—
Lens blazes the perfect path!

With data views and layers deep,
Finally, a dashboard you'll keep.
So here's to Lens, a beauty so true:
That nobody can take away from you.

---

Minimal Configuration Examples

Minimal Lens Metric Chart:

dashboards:
  - name: "Key Metrics Dashboard"
    panels:
      - title: "Total Users"
        size: {w: 16, h: 3}
        lens:
          type: metric # Specifies a LensMetricChart
          data_view: "logs-*"
          query: # Optional panel-specific query
            kql: "event.dataset:website.visits"
          primary:
            aggregation: "unique_count"
            field: "user.id"
            label: "Unique Visitors"

Minimal Lens Pie Chart:

dashboards:
  - name: "Traffic Analysis"
    panels:
      - title: "Traffic by Source"
        size: {w: 32, h: 3}
        position: {x: 16, y: 0}
        lens:
          type: pie # Specifies a LensPieChart
          data_view: "weblogs-*"
          metrics:
            - aggregation: "count"
              label: "Sessions"
          breakdowns:
            - type: values
              field: "source.medium"
              label: "Traffic Source"
              size: 5 # Top 5 sources

Full Configuration Options

Lens Panel (panel with a lens: field)

This is the main object for a Lens-based visualization. It inherits from the Base Panel Configuration.

YAML Key	Data Type	Description	Kibana Default	Required
id	string	A unique identifier for the panel. Inherited from BasePanel.	Generated ID	No
title	string	The title displayed on the panel header. Inherited from BasePanel.	"" (empty string)	No
hide_title	boolean	If true, the panel title will be hidden. Inherited from BasePanel.	false	No
description	string	A brief description of the panel. Inherited from BasePanel.	"" (empty string, if None)	No
size	Size object	Defines the panel's width and height. Inherited from BasePanel. See Size Object Configuration.	w: 12, h: 8	No
position	Position object	Defines the panel's x/y coordinates. Inherited from BasePanel. See Position Object Configuration.	Auto-calculated	No
query	LegacyQueryTypes object (KQL or Lucene)	A panel-specific query to filter data for this Lens visualization. See Queries Documentation.	None (uses dashboard query)	No
filters	list of FilterTypes	A list of panel-specific filters. See Filters Documentation.	[] (empty list)	No
lens	LensPanelConfig object	Defines the actual Lens visualization configuration. This includes the inner type plus chart-specific fields.	N/A	Yes

Note: For XY charts (line, bar, area), a layers field is available to add reference lines and additional data layers. See the XY Chart Panel Configuration documentation for details.

---

Lens Metric Chart (lens.type: metric)

Displays a single primary metric, optionally with a secondary metric, a maximum value, and a breakdown dimension.

YAML Key	Data Type	Description	Kibana Default	Required
type	Literal['metric']	Specifies the chart type as a Lens Metric visualization.	metric	Yes
id	string	An optional unique identifier for this specific chart layer.	Generated ID	No
primary	LensMetricTypes object	The primary metric to display. This is the main value shown. See Lens Metrics.	N/A	Yes
secondary	LensMetricTypes object	An optional secondary metric to display alongside the primary. See Lens Metrics.	None	No
maximum	LensMetricTypes object	An optional maximum metric, used for progress bar scale or context. See Lens Metrics.	None	No
breakdown	LensDimensionTypes object	An optional dimension to break down the metric by (e.g., showing primary metric per country). See Lens Dimensions.	None	No
appearance	MetricAppearance object	Visual appearance configuration. See Metric Appearance.	None	No
titles_and_text	MetricTitlesAndText object	Titles and text formatting options. See Metric Titles and Text.	None	No

Metric Appearance

YAML Key	Data Type	Description	Kibana Default	Required
primary.icon	string	Icon identifier to display alongside the primary metric value.	None	No
primary.icon_position	Literal['left', 'right']	Horizontal alignment of the icon.	None	No
primary.background_chart.type	Literal['line', 'bar', 'none']	Background chart mode for the primary metric.	None	No
primary.background_chart.direction	Literal['horizontal', 'vertical']	Direction for bar background charts (type: bar).	None	No
primary.font_size	Literal['default', 'fit', 'custom']	Font size mode for the primary metric value.	None	No
primary.position	Literal['top', 'bottom']	Vertical position of the primary metric value.	None	No
primary.alignment	Literal['left', 'center', 'right']	Text alignment for the primary metric value.	None	No
secondary.alignment	Literal['left', 'center', 'right']	Text alignment for the secondary metric value.	None	No
secondary.label.text	string	Custom label for the secondary metric.	None	No
secondary.label.position	Literal['before', 'after']	Position for the secondary label.	None	No
breakdown.column_count	int	Maximum breakdown columns (minimum 1).	None	No

Metric Titles and Text

YAML Key	Data Type	Description	Kibana Default	Required
subtitle	string	Custom subtitle text displayed below the metric title.	None	No
alignment	Literal['left', 'center', 'right']	Text alignment for the metric title and subtitle.	None	No
weight	Literal['bold', 'normal', 'lighter']	Font weight for the metric title.	None	No

Example (Lens Metric Chart with Styling):

dashboards:
  - name: "Lens Metric Example"
    description: "Example of Lens metric panel with primary, secondary, and breakdown"
    panels:
      - title: "Data Transfer Metrics"
        size: {w: 24, h: 15}
        lens:
          type: metric
          data_view: "logs-*"
          primary:
            aggregation: "sum"
            field: "bytes_transferred"
            label: "Total Data"
            format: { type: "bytes" }
          secondary:
            aggregation: "average"
            field: "response_time_ms"
            label: "Avg Response"
            format: { type: "duration", suffix: " ms" }
          breakdown:
            type: values
            field: "host.name"
            size: 3
            label: "Top Hosts"
          appearance:
            primary:
              background_chart:
                type: bar
                direction: horizontal
              icon: sortUp
              icon_position: right
          titles_and_text:
            subtitle: "Last 24 hours"
            alignment: center
            weight: bold

---

Lens Pie Chart (lens.type: pie)

Visualizes proportions of categories using slices of a pie or a donut chart.

YAML Key	Data Type	Description	Kibana Default	Required
type	Literal['pie']	Specifies the chart type as a Lens Pie visualization.	pie	Yes
id	string	An optional unique identifier for this specific chart layer.	Generated ID	No
data_view	string	The ID or title of the data view (index pattern) for this pie chart.	N/A	Yes
metrics	LensMetricTypes \| list[LensMetricTypes] object	A single metric or list of metrics that determine the size of each slice. See Lens Metrics.	N/A	Yes
breakdowns	list of LensBreakdownTypes objects	One or more breakdowns that determine how the pie is sliced. See Lens Dimensions.	N/A	Yes
appearance	PieChartAppearance object	Formatting options for the chart appearance. See Pie Chart Appearance.	None	No
legend	PieLegend object	Formatting options for the chart legend. See Pie Legend.	None	No
color	ColorValueMapping object	Formatting options for the chart color palette. See Color Mapping.	None	No

Example (Lens Pie Chart):

dashboards:
  - name: "Lens Pie Chart Example"
    description: "Example of Lens pie chart with appearance and legend options"
    panels:
      - title: "Disk Operations by Device"
        size: {w: 24, h: 15}
        lens:
          type: pie
          data_view: "metrics-*"
          metrics:
            - aggregation: "average"
              field: "metrics.system.disk.operations"
              label: "Avg Disk Operations"
          breakdowns:
            - type: values
              field: "resource.attributes.device"
              size: 5
              label: "Device"
          appearance:
            donut: "medium"
            categories:
              position: "inside"
            values:
              format: "percent"
          legend:
            visible: "show"
            width: "large"

---

Lens Dimensions (breakdown for Metric, breakdowns for Pie)

Dimensions define how data is grouped or bucketed in Lens visualizations.

Common Dimension Fields (BaseLensDimension)

All specific dimension types below can include:

YAML Key	Data Type	Description	Kibana Default	Required
id	string	An optional unique identifier for the dimension.	Generated ID	No
label	string	A custom display label for the dimension. If not provided, a label is inferred.	Inferred	No

When these shapes are used in chart fields that accept LensBreakdownTypes instead of LensDimensionTypes (for example pie breakdowns or other breakdown-specific configs), the breakdown variant may also allow collapse. Plain XY dimension / breakdown axes do not support collapse.

Top Values Dimension (type: values)

Groups data by the most frequent unique values of one or more fields. Supports both single-field and multi-field (multi-term) aggregations.

YAML Key	Data Type	Description	Kibana Default	Required
type	Literal['values']	Specifies the dimension type.	N/A	Yes
field	string	Single field to get top values from. Mutually exclusive with fields.	N/A	One of field or fields
fields	list of strings	Multiple fields for multi-term aggregation (minimum 2 fields). Mutually exclusive with field.	N/A	One of field or fields
size	integer	The number of top values to display.	3	No
sort	Sort object	How to sort the terms. by can be a metric label or _term (alphabetical). direction is asc or desc.	Sort by metric, desc	No
show_other_bucket	boolean	If true, groups remaining values into an "Other" bucket.	true	No
include_missing_values	boolean	If true, creates a bucket for documents where the field is missing.	false	No
include	list of strings	A list of specific terms to include. When include_is_regex is true, must contain exactly one entry.	None	No
exclude	list of strings	A list of specific terms to exclude. When exclude_is_regex is true, must contain exactly one entry.	None	No
include_is_regex	boolean	If true, treats the single include value as a regex pattern. include must contain exactly one entry.	false	No
exclude_is_regex	boolean	If true, treats the single exclude value as a regex pattern. exclude must contain exactly one entry.	false	No

Example - Single Field:

breakdowns:
  - type: values
    field: agent.name
    size: 5

Example - Multi-Field:

breakdowns:
  - type: values
    fields:
      - agent.name
      - agent.type
    size: 10
    label: "Agent Name + Type"

Example - Regex Include/Exclude:

breakdowns:
  - type: values
    field: log.level
    include:
      - "^err(or)?$"
    include_is_regex: true
    exclude:
      - "^debug$"
    exclude_is_regex: true

Date Histogram Dimension (type: date_histogram)

Groups data into time-based buckets (e.g., per hour, day).

YAML Key	Data Type	Description	Kibana Default	Required
type	Literal['date_histogram']	Specifies the dimension type.	N/A	Yes
field	string	The date field to use for the histogram.	N/A	Yes
minimum_interval	string	The time interval (e.g., auto, 1h, 1d, 1w).	auto	No
partial_intervals	boolean	If true, includes buckets for time periods that are only partially covered by the data.	true	No

Filters Dimension (type: filters)

Creates buckets based on a list of custom KQL/Lucene queries.

YAML Key	Data Type	Description	Kibana Default	Required
type	Literal['filters']	Specifies the dimension type.	N/A	Yes
filters	list of LensFiltersDimensionFilter objects	A list of filter definitions. Each filter object has query (KQL/Lucene) and an optional label.	N/A	Yes

LensFiltersDimensionFilter Object:

YAML Key	Data Type	Description	Kibana Default	Required
query	LegacyQueryTypes object	The KQL or Lucene query for this filter bucket.	N/A	Yes
label	string	A display label for this filter bucket.	Query string	No

Intervals Dimension (type: intervals)

Groups data into numeric ranges (buckets).

YAML Key	Data Type	Description	Kibana Default	Required
type	Literal['intervals']	Specifies the dimension type.	N/A	Yes
field	string	The numeric field to create intervals from.	N/A	Yes
intervals	list of LensIntervalsDimensionInterval objects	A list of custom interval ranges. If not provided, granularity is used.	None	No
granularity	integer (1-7)	Divides the field into evenly spaced intervals. 1 is coarsest, 7 is finest.	4	No
include_empty_intervals	boolean	If true, shows a bucket for documents with missing values for the field.	false	No

LensIntervalsDimensionInterval Object:

YAML Key	Data Type	Description	Kibana Default	Required
from	integer	The start of the interval (inclusive).	None	No
to	integer	The end of the interval (exclusive).	None	No
label	string	A display label for this interval bucket.	Auto-generated	No

---

Lens Metrics (primary, secondary, maximum for Metric; metrics for Pie)

Metrics define the calculations performed on your data (e.g., count, sum, average).

Common Metric Fields (BaseLensMetric)

All specific metric types below can include:

YAML Key	Data Type	Description	Kibana Default	Required
id	string	An optional unique identifier for the metric.	Generated ID	No
label	string	A custom display label for the metric. If not provided, a label is inferred.	Inferred	No
format	LensMetricFormatTypes object	How to format the metric's value (e.g., number, bytes, percent). See Metric Formatting.	Default for type	No
filter	LegacyQueryTypes object	A KQL or Lucene query to filter data before this metric is calculated.	None	No

Aggregated Metric Types

These metrics perform an aggregation on a field.

Count / Unique Count (aggregation: count or aggregation: unique_count)

YAML Key	Data Type	Description	Kibana Default	Required
aggregation	Literal['count', 'unique_count']	Type of count.	N/A	Yes
field	string	For unique_count, the field whose unique values are counted. For count, optional (counts all documents if None).	None for count	No (Yes for unique_count)
exclude_zeros	boolean	If true, zero values are excluded from the aggregation.	true	No

Sum (aggregation: sum)

YAML Key	Data Type	Description	Kibana Default	Required
aggregation	Literal['sum']	Specifies sum aggregation.	sum	Yes
field	string	The numeric field to sum.	N/A	Yes
exclude_zeros	boolean	If true, zero values are excluded from the sum.	true	No

Min, Max, Average, Median (aggregation: min / max / average / median)

YAML Key	Data Type	Description	Kibana Default	Required
aggregation	Literal['min', 'max', 'average', 'median']	The aggregation type.	N/A	Yes
field	string	The numeric field for the aggregation.	N/A	Yes

Last Value (aggregation: last_value)

YAML Key	Data Type	Description	Kibana Default	Required
aggregation	Literal['last_value']	Retrieves the most recent value of a field.	last_value	Yes
field	string	The field whose last value is retrieved.	N/A	Yes
date_field	string	The date field used to determine the "last" value.	@timestamp	No

Percentile (aggregation: percentile)

YAML Key	Data Type	Description	Kibana Default	Required
aggregation	Literal['percentile']	Calculates the value at a specific percentile.	percentile	Yes
field	string	The numeric field for percentile calculation.	N/A	Yes
percentile	integer	The percentile to calculate (e.g., 95 for 95th percentile).	N/A	Yes

Percentile Rank (aggregation: percentile_rank)

YAML Key	Data Type	Description	Kibana Default	Required
aggregation	Literal['percentile_rank']	Determines the rank of a specific value within the dataset.	percentile_rank	Yes
field	string	The numeric field for percentile rank calculation.	N/A	Yes
rank	integer	The value for which to find the percentile rank.	N/A	Yes

Formula Metric

Allows custom calculations using Kibana's native formula syntax. Formulas enable complex calculations that combine multiple aggregations, field operations, and mathematical expressions.

YAML Key	Data Type	Description	Kibana Default	Required
formula	string	The formula string using Kibana formula syntax.	N/A	Yes
label	string	A custom display label for the metric.	"Formula"	No
format	LensMetricFormatTypes object	How to format the metric's value.	Default number format	No

Example Formulas:

Simple arithmetic:

primary:
  formula: "count() / 100"
  label: "Count Percentage"

Field aggregations:

primary:
  formula: "max(response.time) - min(response.time)"
  label: "Response Time Range"
  format:
    type: duration

With filters:

primary:
  formula: "count(kql='status:error') / count() * 100"
  label: "Error Rate %"
  format:
    type: percent

Number formatting:

primary:
  formula: "average(bytes)"
  label: "Avg Bytes"
  format:
    type: bytes
    compact: true

---

Metric Formatting (format field within a metric)

Defines how metric values are displayed in visualizations.

Standard Format

Standard format configuration for displaying metric values.

Supports common numeric formats with optional suffix and compact notation.

Attributes:

Name	Type	Description
type	Literal['number', 'bytes', 'bits', 'percent', 'duration']	The format type for the metric value. Available formats: - number: Plain numeric value with optional decimal places - bytes: Byte size formatting (B, KB, MB, GB, TB) - bits: Bit size formatting (b, Kb, Mb, Gb, Tb) - percent: Percentage formatting with % symbol - duration: Time duration formatting (ms, s, m, h, d)
decimals	int | None	The number of decimal places to display. If not specified, defaults to 2 for number/bytes/percent, 0 for bits/duration.
suffix	str | None	Optional suffix to display after the formatted number (e.g., " requests", " users").
compact	bool | None	Whether to use compact notation (e.g., 1.2K instead of 1200). Defaults to Kibana's behavior.

Show JSON schema:

{
  "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"
}

Default Decimal Places (Kibana):

When no decimals or pattern is specified, Kibana applies these defaults:

• number: 2 decimal places
• bytes: 2 decimal places
• bits: 0 decimal places
• percent: 2 decimal places
• duration: 0 decimal places (uses smart duration formatting like "1m 30s")

Use the decimals field to override these defaults with a specific number of decimal places. This provides a simpler alternative to using pattern for controlling decimal precision.

Custom Format

Custom format configuration for metrics using numeral.js patterns.

Use this for complete control over numeric formatting with numeral.js syntax.

Attributes:

Name	Type	Description
type	Literal['custom']	Format type identifier. Must be 'custom' for custom formats.
decimals	int | None	The number of decimal places to display. If not specified, defaults to 0.
pattern	str	numeral.js format pattern (e.g., "0,0.00" for comma-separated numbers with 2 decimals).
suffix	str | None	Optional suffix to display after the formatted number (e.g., " requests", " users").
compact	bool | None	Whether to use compact notation (e.g., 1.2K instead of 1200). Defaults to Kibana's behavior.

Show JSON schema:

{
  "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"
}

---

Pie Chart Specific Formatting

These objects are used within the LensPieChart configuration.

Pie Chart Appearance (appearance field)

YAML Key	Data Type	Description	Kibana Default	Required
donut	Literal['small', 'medium', 'large']	If set, creates a donut chart with the specified hole size.	None (pie)	No

Pie Labels and Values (appearance.categories and appearance.values)

YAML Key	Data Type	Description	Kibana Default	Required
appearance.categories.position	Literal['hide', 'inside', 'auto']	How to display labels for each slice.	auto	No
appearance.values.format	Literal['hide', 'integer', 'percent']	How to display the value for each slice.	percent	No
appearance.values.decimal_places	integer (0-10)	Number of decimal places for slice values.	2	No

titles_and_text is not accepted in 0.4.0; use appearance.categories and appearance.values fields instead (or run kb-dashboard upgrade).

Pie Legend (legend field)

YAML Key	Data Type	Description	Kibana Default	Required
visible	Literal['show', 'hide', 'auto']	Controls legend visibility.	auto	No
width	Literal['small', 'medium', 'large', 'extra_large']	Width of the legend area.	medium	No
truncate_labels	integer (0-5)	Max number of lines for legend labels before truncating. 0 disables truncation.	1	No

Color Mapping (color field)

YAML Key	Data Type	Description	Kibana Default	Required
palette	string	The ID of the color palette to use (e.g., default, elasticColors).	default	Yes

Related Documentation

• Base Panel Configuration
• Dashboard Configuration
• Queries Configuration
• Filters Configuration