Dashboard Panels

Panels are the building blocks of Grafana dashboards. Each panel displays a visualization of your data using queries, transformations, and customizable options.

Panel Model

The PanelModel class represents a panel’s configuration and state:

interface PanelModel {
  id: number;                    // Unique panel ID within dashboard
  type: string;                  // Visualization type (e.g., "timeseries")
  title: string;                 // Panel title
  gridPos: GridPos;              // Position and size on grid
  targets: DataQuery[];          // Array of queries
  transformations?: DataTransformerConfig[];  // Data transformations
  datasource: DataSourceRef | null;  // Data source reference
  options: Record<string, any>;  // Panel-specific options
  fieldConfig: FieldConfigSource;  // Field configuration and overrides
  transparent: boolean;          // Transparent background
  description?: string;          // Panel description
  links?: DataLink[];            // Panel links
}

Panel Types

Grafana includes many built-in visualizations:

Time Series Visualizations

Time Series

Line, bar, and area charts for time-series data with multiple series support

State Timeline

Visualize state changes over time with categorical data

Status History

Show periodic state over time in a grid format

Trend

Display trends and sparklines for single metrics

Statistical Visualizations

Stat

Single value with optional graph and thresholds

Gauge

Radial or linear gauge for displaying single values

Bar Gauge

Horizontal or vertical bars with threshold colors

Heatmap

Visualize value distribution over time in a heat map

Graph Visualizations

Bar Chart

Categorical data visualization with grouped or stacked bars

Histogram

Distribution of values across buckets

Pie Chart

Proportional data visualization

Candlestick

Financial data with OHLC (Open, High, Low, Close) values

Data Visualizations

Table

Tabular data display with sorting, filtering, and formatting

Logs

Log line display with parsing and filtering

Node Graph

Network topology and relationship visualization

Traces

Distributed tracing visualization

Geo & Special

Geomap

Geographical data on interactive maps

Canvas

Custom visualizations with drag-and-drop elements

Dashboard List

List of dashboards matching criteria

Alert List

Active alerts and their states

Creating and Configuring Panels

Adding a Panel

Enter Edit Mode

Click Add → Visualization or the + icon on an existing panel

Select Visualization

Choose the visualization type from the picker

Configure Query

Build your query using the data source query editor

Customize Options

Adjust panel options, field config, and overrides

Apply Changes

Click Apply to save the panel to the dashboard

Panel Editor Interface

The panel editor has three main sections:

interface PanelEditorLayout {
  visualization: {
    preview: PanelPreview;     // Live preview of panel
    controls: VisualizationPicker;
  };
  queryEditor: {
    tabs: ['Query', 'Transform', 'Alert'];  // Data pipeline tabs
    queries: DataQuery[];      // Query configurations
    transformations: DataTransformerConfig[];
  };
  optionsPane: {
    sections: [
      'Panel options',         // Title, description, links
      'Tooltip',              // Tooltip configuration
      'Legend',               // Legend settings
      'Graph styles',         // Visualization-specific
      'Standard options',     // Field config defaults
      'Overrides'            // Field-specific overrides
    ];
  };
}

Query Configuration

Panels can have multiple queries that are combined:

interface DataQuery {
  refId: string;              // Unique reference ID (A, B, C...)
  datasource?: DataSourceRef; // Optional datasource override
  hide?: boolean;             // Hide this query
  // ... datasource-specific query properties
}

// Example: Multiple queries in a panel
targets: [
  {
    refId: "A",
    expr: "rate(http_requests_total[5m])",
    legendFormat: "Requests/sec"
  },
  {
    refId: "B",
    expr: "rate(http_errors_total[5m])",
    legendFormat: "Errors/sec"
  }
]

Query Options

Control query behavior:

interface QueryOptions {
  maxDataPoints?: number;      // Maximum data points to return
  interval?: string;           // Minimum time interval (e.g., "1m")
  cacheTimeout?: string;       // Cache duration (e.g., "60")
  queryCachingTTL?: number;    // Query cache TTL in milliseconds
  timeFrom?: string;           // Panel time override (e.g., "now-1h")
  timeShift?: string;          // Shift time range (e.g., "1d")
  hideTimeOverride?: boolean;  // Hide time override indicator
}

Field Configuration

Field configuration controls how data is displayed:

interface FieldConfigSource {
  defaults: FieldConfig;       // Default config for all fields
  overrides: FieldConfigOverride[];  // Field-specific overrides
}

interface FieldConfig {
  unit?: string;               // Display unit (e.g., "bytes", "percent")
  decimals?: number;           // Decimal precision
  min?: number;                // Minimum value
  max?: number;                // Maximum value
  displayName?: string;        // Override field display name
  color?: FieldColor;          // Color configuration
  thresholds?: ThresholdsConfig;  // Threshold settings
  mappings?: ValueMapping[];   // Value mappings
  links?: DataLink[];          // Data links
  custom?: Record<string, any>;  // Visualization-specific config
}

Thresholds

Define color-coded thresholds:

interface ThresholdsConfig {
  mode: ThresholdsMode;  // 'absolute' or 'percentage'
  steps: Threshold[];    // Array of threshold steps
}

interface Threshold {
  value: number;         // Threshold value
  color: string;         // Color when value exceeds threshold
}

// Example
thresholds: {
  mode: 'absolute',
  steps: [
    { value: 0, color: 'green' },      // 0-80: green
    { value: 80, color: 'yellow' },    // 80-90: yellow
    { value: 90, color: 'red' }        // 90+: red
  ]
}

Value Mappings

Map values to text or colors:

interface ValueMapping {
  type: 'value' | 'range' | 'regex' | 'special';
  options: {
    match?: string | number;    // For 'value' type
    from?: number;              // For 'range' type
    to?: number;
    pattern?: string;           // For 'regex' type
    result: {
      text?: string;
      color?: string;
      icon?: string;
    };
  };
}

// Example: Map numeric status to text
mappings: [
  {
    type: 'value',
    options: {
      match: 1,
      result: { text: 'OK', color: 'green' }
    }
  },
  {
    type: 'value',
    options: {
      match: 0,
      result: { text: 'Failed', color: 'red' }
    }
  }
]

Data Transformations

Transform query results before visualization:

interface DataTransformerConfig {
  id: string;              // Transformer ID
  options: any;            // Transformer-specific options
  disabled?: boolean;      // Disable transformation
}

// Common transformations
transformations: [
  {
    id: 'filterFieldsByName',
    options: {
      include: { names: ['time', 'value'] }
    }
  },
  {
    id: 'calculateField',
    options: {
      mode: 'binary',
      reduce: { reducer: 'sum' },
      binary: {
        left: 'A',
        operator: '/',
        right: 'B'
      },
      alias: 'Ratio'
    }
  }
]

Common Transformations

Filter by Name

Include or exclude fields by name or regex pattern

Organize Fields

Reorder, rename, and hide fields

Join by Field

Combine multiple queries by a common field

Add Field from Calculation

Create calculated fields using math expressions

Group By

Group data by field values

Sort By

Sort data by field values

Reduce

Reduce multiple values to single values using aggregation

Series to Rows

Convert time series to row format

Panel Links

Add clickable links to panels:

interface DataLink {
  title: string;              // Link text
  url: string;                // URL with variable support
  targetBlank?: boolean;      // Open in new tab
  onClick?: Function;         // Custom click handler
}

// Example: Link to detailed dashboard
links: [
  {
    title: "View Details",
    url: "/d/xyz/${__field.name}?var-instance=${__field.labels.instance}",
    targetBlank: true
  }
]

Panel links support variable interpolation including ${__field.name}, ${__field.labels.labelname}, ${__value.raw}, and ${__value.text}.

Panel Repeating

Dynamically create panels based on variable values:

interface PanelRepeat {
  repeat?: string;            // Variable name to repeat by
  repeatDirection?: 'h' | 'v';  // Horizontal or vertical
  maxPerRow?: number;         // Max panels per row (horizontal only)
}

// Example: Create panel for each server
repeat: "server"              // Variable named "server"
repeatDirection: "h"          // Arrange horizontally
maxPerRow: 4                  // 4 panels per row

Create a Variable

Add a multi-value variable in dashboard settings

Configure Panel Repeat

In panel editor, go to Panel options → Repeat options

Select Variable

Choose the variable to repeat by

Set Direction

Choose horizontal or vertical layout

Panel Options

Each panel type has specific options. Common options include:

interface CommonPanelOptions {
  title?: string;             // Panel title
  description?: string;       // Panel description (tooltip)
  transparent?: boolean;      // Transparent background
  links?: DataLink[];         // Panel links
  
  // Common display options
  legend?: {
    show: boolean;
    placement: 'bottom' | 'right' | 'top';
    displayMode: 'list' | 'table';
    calcs: string[];          // Calculations to show
  };
  
  tooltip?: {
    mode: 'single' | 'multi' | 'none';
    sort: 'none' | 'asc' | 'desc';
  };
}

Best Practices

Follow these guidelines for effective panel design:

Query Optimization

Use appropriate time ranges for your data frequency
Set maxDataPoints to match panel width
Enable query caching for expensive queries
Use query interval hints: $__interval or $__rate_interval

Visual Design

Keep panel titles clear and concise
Use consistent color schemes across related panels
Add descriptions for complex visualizations
Choose appropriate visualization types for your data

Performance

Limit the number of series per panel (aim for less than 50)
Use transformations efficiently
Avoid unnecessary field overrides
Consider panel caching for static data

Advanced Features

Library Panels

Create reusable panels across dashboards:

interface LibraryPanel {
  uid: string;                // Library panel UID
  name: string;               // Panel name
  model: PanelModel;          // Panel configuration
  version: number;            // Version number
}

// Reference in dashboard
library Panel: {
  uid: "lib-panel-123",
  name: "CPU Usage Panel"
}

Panel Migration

Panels can define migration handlers:

interface PanelPlugin {
  onPanelMigration?: (panel: PanelModel) => Promise<Partial<PanelOptions>>;
  shouldMigrate?: (panel: PanelModel) => boolean;
}

// Automatically runs when pluginVersion changes

Next Steps

Dashboard Variables

Add dynamic filtering with variables

Templating

Use template syntax in queries and titles

Transformations

Learn about all available transformations

Sharing

Share individual panels or entire dashboards

Overview

Getting Started

Dashboards

Data Sources

Alerting

Explore

Visualization

​Dashboard Panels

​Panel Model

​Panel Types

​Time Series Visualizations

Time Series

State Timeline

Status History

Trend

​Statistical Visualizations

Stat

Gauge

Bar Gauge

Heatmap

​Graph Visualizations

Bar Chart

Histogram

Pie Chart

Candlestick

​Data Visualizations

Table

Logs

Node Graph

Traces

​Geo & Special

Geomap

Canvas

Dashboard List

Alert List

​Creating and Configuring Panels

​Adding a Panel

​Panel Editor Interface

​Query Configuration

​Query Options

​Field Configuration

​Thresholds

​Value Mappings

​Data Transformations

​Common Transformations

Filter by Name

Organize Fields

Join by Field

Add Field from Calculation

Group By

Sort By

Reduce

Series to Rows

​Panel Links

​Panel Repeating

​Panel Options

​Best Practices

​Query Optimization

​Visual Design

​Performance

​Advanced Features

​Library Panels

​Panel Migration

​Next Steps

Dashboard Variables

Templating

Transformations

Sharing

Dashboard Panels

Panel Model

Panel Types

Time Series Visualizations

Statistical Visualizations

Graph Visualizations

Data Visualizations

Geo & Special

Creating and Configuring Panels

Adding a Panel

Panel Editor Interface

Query Configuration

Query Options

Field Configuration

Thresholds

Value Mappings

Data Transformations

Common Transformations

Panel Links

Panel Repeating

Panel Options

Best Practices

Query Optimization

Visual Design

Performance

Advanced Features

Library Panels

Panel Migration

Next Steps