Core Concepts

This guide covers the essential concepts you need to understand to work effectively with Grafana.

Dashboards

Dashboards are the primary organizational unit in Grafana. A dashboard is a collection of panels arranged in a grid layout that provides a unified view of your data.

Dashboard Structure

Dashboards are stored as JSON and include:

// From pkg/services/dashboards
interface Dashboard {
  id?: number;              // Database ID (null for new dashboards)
  uid: string;              // Unique identifier
  title: string;            // Dashboard name
  tags: string[];           // Searchable tags
  timezone: string;         // "browser" or specific timezone
  panels: Panel[];          // Array of visualization panels
  templating: {
    list: VariableModel[];  // Template variables
  };
  time: {
    from: string;           // Time range start (e.g., "now-6h")
    to: string;             // Time range end (e.g., "now")
  };
  refresh: string;          // Auto-refresh interval
  version: number;          // Version number (increments on save)
  links: DashboardLink[];   // Dashboard links and navigation
}

Key Dashboard Features

Grid Layout

Panels are positioned on a 24-column grid with configurable height. Drag and drop to rearrange, resize by dragging corners.

Version Control

Every save creates a new version. Access dashboard history to view changes, compare versions, and restore previous states.

Folders

Organize dashboards into folders for better structure and access control via the folder service (pkg/services/folder).

Variables

Template variables create dynamic, reusable dashboards. Variables appear as dropdowns in the dashboard header.

Panels

Panels are the building blocks of dashboards. Each panel displays data from one or more queries using a specific visualization type.

Panel Types

Grafana includes many built-in panel types:

Time Series: Line, bar, and area charts for time-series data
Stat: Single value with optional graph sparkline
Gauge: Radial or linear gauge for showing values against thresholds
Bar Chart: Categorical data visualization
Table: Tabular data with sorting and filtering
Logs: Log line visualization with filtering and highlighting
Heatmap: Density visualization for histogram data

Panel Data Flow

// packages/grafana-data/src/types/panel.ts
interface PanelData {
  state: LoadingState;      // "Loading" | "Done" | "Error" | "Streaming"
  series: DataFrame[];      // Data frames with field overrides applied
  timeRange: TimeRange;     // Current time range from the request
  request?: DataQueryRequest;  // Original query request
  errors?: DataQueryError[];   // Any query errors
  annotations?: DataFrame[];   // Annotation data
}

interface PanelProps<T = any> {
  id: number;               // Unique panel ID
  data: PanelData;          // Query results and state
  timeRange: TimeRange;     // Dashboard time range
  timeZone: TimeZone;       // Dashboard timezone
  options: T;               // Panel-specific options
  fieldConfig: FieldConfigSource;  // Field configuration
  width: number;            // Panel width in pixels
  height: number;           // Panel height in pixels
  transparent: boolean;     // Transparent background
  onChangeTimeRange: (timeRange: AbsoluteTimeRange) => void;
}

Field Configuration

Field configuration controls how data values are displayed:

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

interface FieldConfig {
  unit?: string;             // Display unit (e.g., "bytes", "ms", "percent")
  decimals?: number;         // Decimal places to show
  min?: number;              // Minimum value for scales
  max?: number;              // Maximum value for scales
  thresholds?: ThresholdsConfig;  // Threshold configuration
  color?: FieldColor;        // Color settings
  mappings?: ValueMapping[]; // Value mappings
  links?: DataLink[];        // Data links
}

Data Sources

Data sources are the connection between Grafana and your data. Each data source represents a database, API, or service that Grafana can query.

Data Source Types

Grafana supports numerous data sources: Time Series Databases:

Prometheus
InfluxDB
Graphite
TimescaleDB

Logging Systems:

Loki
Elasticsearch

Relational Databases:

PostgreSQL
MySQL
Microsoft SQL Server

Cloud Services:

AWS CloudWatch
Azure Monitor
Google Cloud Monitoring

Data Source Plugin Architecture

// packages/grafana-data/src/types/datasource.ts
abstract class DataSourceApi<
  TQuery extends DataQuery = DataQuery,
  TOptions extends DataSourceJsonData = DataSourceJsonData
> {
  name: string;              // Data source name
  type: string;              // Data source type/plugin ID
  uid: string;               // Unique identifier
  meta: DataSourcePluginMeta; // Plugin metadata
  
  // Core query method - must be implemented
  abstract query(request: DataQueryRequest<TQuery>): Observable<DataQueryResponse>;
  
  // Optional: Test the data source connection
  testDatasource?(): Promise<TestDataSourceResponse>;
  
  // Optional: Variable query support
  metricFindQuery?(query: any, options?: any): Promise<MetricFindValue[]>;
  
  // Optional: Annotation support
  annotationQuery?(options: AnnotationQueryRequest<TQuery>): Promise<AnnotationEvent[]>;
}

Data Source Configuration

Data sources are configured via the API:

// pkg/api/datasources.go
type DataSourceListItemDTO struct {
    OrgId     int64  `json:"orgId"`
    Id        int64  `json:"id"`
    UID       string `json:"uid"`
    Name      string `json:"name"`
    Type      string `json:"type"`        // Plugin ID
    TypeName  string `json:"typeName"`    // Human-readable name
    Access    string `json:"access"`      // "proxy" or "direct"
    Url       string `json:"url"`
    Database  string `json:"database"`
    User      string `json:"user"`
    BasicAuth bool   `json:"basicAuth"`
    IsDefault bool   `json:"isDefault"`
    JsonData  map[string]interface{} `json:"jsonData"`
    ReadOnly  bool   `json:"readOnly"`
}

Queries

Queries define what data to retrieve from data sources. Each panel can have multiple queries that are executed and combined.

Query Model

// @grafana/schema
interface DataQuery {
  refId: string;             // Query identifier (A, B, C, etc.)
  datasource?: DataSourceRef; // Data source reference
  hide?: boolean;            // Hide query results
  queryType?: string;        // Query type (datasource-specific)
}

interface DataSourceRef {
  type?: string;             // Data source plugin type
  uid?: string;              // Data source UID
}

Query Execution Flow

Query Request

Panel creates a DataQueryRequest with queries, time range, and other parameters.

Data Source Query

Data source plugin executes the query against the backend database or API.

Data Frames

Results are returned as DataFrame objects - a columnar data structure.

Transformations

Optional data transformations are applied (merge, filter, calculate fields, etc.).

Field Config

Field configuration (units, thresholds, colors) is applied to the data.

Rendering

The panel plugin renders the processed data according to its visualization type.

Time Ranges

Time ranges control what data is displayed. Grafana supports both relative and absolute time ranges.

Time Range Types

// Relative time ranges
interface RawTimeRange {
  from: string;              // "now-6h", "now-1d", "now-7d"
  to: string;                // "now"
}

// Absolute time ranges
interface AbsoluteTimeRange {
  from: number;              // Unix timestamp in milliseconds
  to: number;                // Unix timestamp in milliseconds
}

interface TimeRange {
  from: DateTime;            // Parsed start time
  to: DateTime;              // Parsed end time
  raw: RawTimeRange;         // Original unparsed range
}

Common Time Range Examples

now-5m to now: Last 5 minutes
now-1h to now: Last hour
now-24h to now: Last 24 hours
now/d to now/d: Today so far
now-7d/d to now-1d/d: Previous week

Variables

Variables enable dynamic dashboards by allowing users to change query parameters through dropdown menus.

Variable Types

Query Variables: Populated by running a query against a data source

// Example: List of servers from Prometheus
{
  type: "query",
  name: "server",
  query: "label_values(up, instance)",
  datasource: { uid: "prometheus-uid" }
}

Custom Variables: Manually defined list of values

{
  type: "custom",
  name: "environment",
  query: "prod,staging,dev"
}

Interval Variables: Time interval for grouping

{
  type: "interval",
  name: "interval",
  auto: true,
  auto_min: "10s",
  auto_count: 30
}

Data Source Variables: List of data sources

{
  type: "datasource",
  name: "datasource",
  query: "prometheus"  // Filter by type
}

Using Variables in Queries

Reference variables using $variable or ${variable} syntax:

# Prometheus query with variables
rate(http_requests_total{instance="$server", env="$environment"}[$interval])

Variables are interpolated by Grafana before sending queries to data sources.

Alerts

Grafana Alerting allows you to define alert rules that continuously evaluate queries and send notifications when conditions are met.

Alert Rule Structure

Alert rules are defined in the unified alerting system (pkg/services/ngalert):

// Simplified alert rule model
type AlertRule struct {
    UID          string            // Unique identifier
    Title        string            // Alert name
    Condition    string            // Query RefID to alert on
    Data         []AlertQuery      // Queries to evaluate
    IntervalSeconds int64          // Evaluation interval
    For          time.Duration     // How long condition must be true
    Annotations  map[string]string // Description, runbook URL, etc.
    Labels       map[string]string // Labels for routing
}

Alert States

Normal: Condition is not met
Pending: Condition is met but waiting for “For” duration
Alerting: Condition has been met for longer than “For” duration
NoData: Query returned no data
Error: Error evaluating the alert rule

Notification Channels

Alerts are routed to notification channels based on labels and routing rules:

Slack
Email
PagerDuty
Webhook
Microsoft Teams
OpsGenie
VictorOps
And many more via contact points

Grafana uses a unified alerting system that evaluates alert rules independently of dashboards, providing more reliable alerting.

Plugins

Grafana’s plugin system enables extending functionality with custom panels, data sources, and applications.

Plugin Types

Panel Plugins: Custom visualizations

Located in public/app/plugins/panel/
Built with @grafana/data and @grafana/ui packages

Data Source Plugins: Connect to custom data sources

Backend in pkg/tsdb/ (Go)
Frontend in public/app/plugins/datasource/ (TypeScript)
Use @grafana/plugin-sdk-go for backend

App Plugins: Full applications within Grafana

Can include custom pages, panels, and data sources
Examples in apps/ directory

Plugin Development

Plugins are built using the Grafana plugin SDK:

// Panel plugin example
import { PanelPlugin } from '@grafana/data';

export const plugin = new PanelPlugin(MyPanelComponent)
  .setPanelOptions((builder) => {
    return builder
      .addTextInput({
        path: 'title',
        name: 'Title',
        defaultValue: 'Default Title'
      });
  });

Next Steps

Dashboard Best Practices

Learn how to design effective dashboards with proper layout, naming conventions, and variable usage.

Query Optimization

Optimize your queries for better performance with proper time ranges, aggregation, and caching.

Advanced Alerting

Set up sophisticated alert routing, silencing, and escalation policies.

Plugin Development

Build custom panels and data sources to extend Grafana’s capabilities.

Additional Resources

API Documentation: Backend API routes in pkg/api/
Type Definitions: packages/grafana-data/src/types/
Frontend Architecture: Redux Toolkit slices in feature directories
Schema Definitions: CUE schemas in kinds/ for dashboard structure

Understanding these core concepts provides a solid foundation for working with Grafana effectively, whether you’re creating dashboards, developing plugins, or contributing to the project.

Overview

Getting Started

Dashboards

Data Sources

Alerting

Explore

Visualization

​Core Concepts

​Dashboards

​Dashboard Structure

​Key Dashboard Features

Grid Layout

Version Control

Folders

Variables

​Panels

​Panel Types

​Panel Data Flow

​Field Configuration

​Data Sources

​Data Source Types

​Data Source Plugin Architecture

​Data Source Configuration

​Queries

​Query Model

​Query Execution Flow

​Time Ranges

​Time Range Types

​Common Time Range Examples

​Variables

​Variable Types

​Using Variables in Queries

​Alerts

​Alert Rule Structure

​Alert States

​Notification Channels

​Plugins

​Plugin Types

​Plugin Development

​Next Steps

Dashboard Best Practices

Query Optimization

Advanced Alerting

Plugin Development

​Additional Resources

Core Concepts

Dashboards

Dashboard Structure

Key Dashboard Features

Panels

Panel Types

Panel Data Flow

Field Configuration

Data Sources

Data Source Types

Data Source Plugin Architecture

Data Source Configuration

Queries

Query Model

Query Execution Flow

Time Ranges

Time Range Types

Common Time Range Examples

Variables

Variable Types

Using Variables in Queries

Alerts

Alert Rule Structure

Alert States

Notification Channels

Plugins

Plugin Types

Plugin Development

Next Steps

Additional Resources