Legend Configuration Guide¶

Legends help users understand what colors, lines, and shapes represent in their charts. This guide covers legend configuration options across different chart types in the kb-yaml-to-lens compiler.

Overview¶

The legend displays a mapping between visual elements (colors, patterns, etc.) and the data they represent. Different chart types support different legend options:

XY Charts (line, bar, area): Support position, width, visibility, and label truncation
Pie Charts: Support position (via width), visibility, nested legends, and label truncation
Heatmap Charts: Support position and visibility for the color scale legend

Legend Options by Chart Type¶

XY Chart Legends¶

XY charts (line, bar, and area charts) provide comprehensive legend customization:

dashboards:
  - name: "XY Chart with Legend"
    panels:
      - title: "Request Count by Service"
        size: {w: 24, h: 15}
        lens:
          type: line
          data_view: "logs-*"
          dimension:
            field: "@timestamp"
            type: date_histogram
          breakdown:
            field: "service.name"
            type: values
          metrics:
            - aggregation: count
          legend:
            visible: show              # show, hide, or auto
            position: right             # top, bottom, left, or right
            width: medium               # small, medium, large, extra_large
            show_single_series: false   # Show legend even with one series
            truncate_labels: 1          # Lines to truncate labels (0-5)

Available Options:

Option	Values	Description	Default	Required
`visible`	`show`, `hide`, `auto`	Control legend visibility	`show`	No
`position`	`top`, `bottom`, `left`, `right`	Legend placement	`right`	No
`width`	`small`, `medium`, `large`, `extra_large`	Legend width/height	Auto	No
`show_single_series`	`true`, `false`	Show legend for single series	`false`	No
`truncate_labels`	`0` to `5`	Lines before truncation (0 = no truncation)	`1`	No

Pie Chart Legends¶

Pie charts have a simplified legend configuration focused on label formatting:

dashboards:
  - name: "Pie Chart with Legend"
    panels:
      - title: "Traffic by Source"
        size: {w: 24, h: 15}
        lens:
          type: pie
          data_view: "logs-*"
          breakdowns:
            - field: "traffic.source"
              type: values
          metrics:
            - aggregation: count
          legend:
            visible: auto              # show, hide, or auto
            width: medium               # small, medium, large, extra_large
            truncate_labels: 1          # Lines to truncate labels (0-5)
            nested: false               # Nested format for multi-level pies
            show_single_series: false   # Show legend for single series

Available Options:

Option	Values	Description	Default	Required
`visible`	`show`, `hide`, `auto`	Control legend visibility	`auto`	No
`width`	`small`, `medium`, `large`, `extra_large`	Legend width	`medium`	No
`truncate_labels`	`0` to `5`	Lines before truncation (0 = no truncation)	`1`	No
`nested`	`true`, `false`	Nested format for multi-level pies	`false`	No
`show_single_series`	`true`, `false`	Show legend for single series	`false`	No

Heatmap Chart Legends¶

Heatmap charts display a color scale legend:

dashboards:
  - name: "Heatmap with Legend"
    panels:
      - title: "Activity Heatmap"
        size: {w: 24, h: 15}
        lens:
          type: heatmap
          data_view: "logs-*"
          x_axis:
            field: "@timestamp"
            type: date_histogram
          y_axis:
            field: "service.name"
            type: values
          metric:
            aggregation: count
          appearance:
            legend:
              visible: show    # show or hide (auto not supported)
              position: right  # top, bottom, left, or right

Available Options:

Option	Values	Description	Default	Required
`visible`	`show`, `hide`	Control legend visibility (auto not supported)	`show`	No
`position`	`top`, `bottom`, `left`, `right`	Legend placement	`right`	No

Note: Heatmap legends do not support the auto visibility option. Use show or hide explicitly.

Best Practices¶

1. Choose Appropriate Visibility¶

Use show when the legend is essential for understanding the chart (e.g., multiple series with similar colors)
Use hide when the chart is self-explanatory or space is limited (e.g., single metric over time)
Use auto (XY and Pie only) to let Kibana decide based on the data

2. Optimize Legend Position¶

Right position (default): Works well for most time series charts
Bottom position: Better for wide dashboards or charts with many series
Top position: Useful when you want the legend prominently displayed
Left position: Rarely used, but can work for charts with long series names

3. Manage Long Labels¶

Use truncate_labels to prevent legends from taking up too much space:

legend:
  truncate_labels: 2  # Truncate to 2 lines

Set to 0 to disable truncation if you need to see full labels:

legend:
  truncate_labels: 0  # No truncation

4. Width Considerations¶

Choose legend width based on the number of series and label length:

# For many series or long labels
legend:
  width: large

# For few series with short labels
legend:
  width: small

5. Single Series Charts¶

For single-series charts, consider hiding the legend to save space:

legend:
  show_single_series: false  # Default - hide legend for single series

Or show it for consistency across dashboards:

legend:
  show_single_series: true  # Always show legend

Common Patterns¶

Pattern 1: Hide Legend for Simple Time Series¶

lens:
  type: line
  data_view: "logs-*"
  dimension:
    field: "@timestamp"
    type: date_histogram
  metrics:
    - aggregation: count
      label: "Total Requests"
  legend:
    visible: hide  # Single metric doesn't need legend

Pattern 2: Bottom Legend for Wide Charts¶

lens:
  type: bar
  data_view: "logs-*"
  dimension:
    field: "service.name"
    type: values
  breakdown:
    field: "http.response.status_code"
    type: values
    size: 10
  metrics:
    - aggregation: count
  legend:
    position: bottom  # Better for many categories
    width: small
    truncate_labels: 1

Pattern 3: Nested Pie Chart Legend¶

lens:
  type: pie
  data_view: "logs-*"
  breakdowns:
    - field: "service.name"
      type: values
    - field: "http.response.status_code"
      type: values
  metrics:
    - aggregation: count
  legend:
    visible: show
    nested: true       # Hierarchical legend for multi-level pie
    width: large
    truncate_labels: 2

Pattern 4: Compact Heatmap Legend¶

lens:
  type: heatmap
  data_view: "logs-*"
  x_axis:
    field: "@timestamp"
    type: date_histogram
  y_axis:
    field: "host.name"
    type: values
  metric:
    aggregation: average
    field: "cpu.usage"
  appearance:
    legend:
      visible: show
      position: bottom  # Save horizontal space

Examples¶

For comprehensive examples of legend configurations across different chart types, see:

XY Charts - XY chart configuration and legend options
Pie Charts - Pie chart configuration and legend options
Heatmap Charts - Heatmap chart configuration and legend options
Base Panel Configuration - Common panel configuration options

Legend Configuration Guide¶

Overview¶

Legend Options by Chart Type¶

XY Chart Legends¶

Pie Chart Legends¶

Heatmap Chart Legends¶

Best Practices¶

1. Choose Appropriate Visibility¶

2. Optimize Legend Position¶

3. Manage Long Labels¶

4. Width Considerations¶

5. Single Series Charts¶

Common Patterns¶

Pattern 1: Hide Legend for Simple Time Series¶

Pattern 2: Bottom Legend for Wide Charts¶

Pattern 3: Nested Pie Chart Legend¶

Pattern 4: Compact Heatmap Legend¶

Examples¶

Related Documentation¶