Skip to main content

Histograms

Introduction​

Histograms are powerful visualization tools that help you understand the distribution of your data by grouping values into buckets (or bins) and displaying the frequency of values in each bucket. Unlike time series graphs that show changes over time, histograms show you the shape and spread of your data at a specific point in time.

In Grafana, histograms are particularly useful for visualizing:

  • Request durations
  • Response sizes
  • Resource utilization distributions
  • Any numeric data where understanding the distribution pattern is important

By the end of this tutorial, you'll understand how histograms work, how to create them in Grafana, and how to interpret the results to gain insights from your data.

Understanding Histogram Basics​

What is a Histogram?​

A histogram is a graphical representation that organizes data into continuous, non-overlapping intervals called bins. It then counts how many data points fall into each bin and displays these counts as bars.

Key components of a histogram include:

  • Bins (or buckets): The x-axis divisions that group your data
  • Frequency: The y-axis showing how many data points fall into each bin
  • Distribution shape: The overall pattern formed by the bars (normal, skewed, bimodal, etc.)

How Histograms Differ from Bar Charts​

While they may look similar, histograms and bar charts serve different purposes:

  • Histograms show distribution of continuous data across ranges
  • Bar charts compare discrete categories
  • Histogram bins are continuous and represent ranges, while bar chart categories are separate entities

Creating Histograms in Grafana​

Grafana offers several ways to create and work with histograms:

  1. Using the Histogram panel
  2. Transforming time series data into histograms
  3. Working with histogram metrics from data sources like Prometheus

Let's explore each approach.

Method 1: Using the Histogram Panel​

Grafana includes a dedicated Histogram panel visualization that can transform your data into a histogram automatically.

To create a basic histogram:

1. Create a new dashboard or edit an existing one
2. Add a new panel
3. Select the Histogram visualization type
4. Configure your data source query to return the numeric values you want to analyze

Basic Configuration Options​

The Histogram panel offers several configuration options:

js
// Example panel JSON configuration
{
  "type": "histogram",
  "options": {
    "bucketSize": 10,  // Size of each bin
    "bucketOffset": 0, // Offset for the first bucket
    "combine": false   // Whether to combine series
  }
}

You can adjust these settings in the panel editor:

  • Bucket size: Controls the width of each bin
  • Bucket offset: Shifts the starting point of the first bin
  • Combine: When enabled, combines multiple series into a single histogram

Method 2: Transforming Time Series Data​

If your data is in time series format, you can use Grafana's transformations to convert it to a histogram:

To transform time series data into a histogram:

1. Create a panel with your time series data
2. Go to the Transform tab
3. Add a "Histogram" transformation
4. Configure the number of buckets or bucket size

This approach is useful when you want to analyze the distribution of values from a time series without setting up histogram-specific metrics at the data source level.

Method 3: Using Histogram Metrics from Data Sources​

Some data sources like Prometheus have native support for histogram metrics. These are pre-aggregated at the data source level.

Example with Prometheus​

Prometheus stores histograms as a set of cumulative counters for configured buckets. To visualize this data:

# Example Prometheus query for a histogram
rate(http_request_duration_seconds_bucket[5m])

Then, in Grafana:

1. Create a new panel
2. Set up your Prometheus query that returns histogram buckets
3. Choose the Histogram visualization
4. In the panel options, enable "From prometheus" under Histogram Mode

Interpreting Histogram Data​

Understanding how to read a histogram is essential for gaining insights from your data.

Common Distribution Patterns​

Different shapes in your histogram can reveal important characteristics of your data:

  • Normal distribution: Bell-shaped, with most values clustered around the middle
  • Skewed distribution:
    • Right-skewed (positive): Tail extends to the right
    • Left-skewed (negative): Tail extends to the left
  • Bimodal distribution: Two distinct peaks, suggesting two different populations
  • Uniform distribution: All bins have similar heights

Analysis Examples​

Let's examine some practical examples of what histograms can tell you about your systems:

Example 1: API Response Times​

Scenario: Analyzing the distribution of API response times

Observations:
- Most responses cluster around 50-100ms (the main peak)
- A small secondary peak at 300-350ms
- A long tail extending beyond 500ms

This pattern might indicate:

  • Normal behavior for most requests (main peak)
  • A specific type of request taking longer (secondary peak)
  • Occasional system issues or complex edge cases (long tail)

Example 2: Resource Utilization​

Scenario: CPU utilization across a server fleet

Observations:
- Bimodal distribution with peaks at 20% and 80% utilization
- Very few servers between 40-60% utilization

This pattern might suggest:

  • Two distinct workload patterns across your infrastructure
  • Opportunity to better balance resources
  • Potential for resource optimization

Advanced Histogram Techniques in Grafana​

Heatmaps: Histograms Over Time​

A heatmap is essentially a series of histograms over time, with color representing frequency. This is useful for tracking how distributions change over time.

To create a heatmap in Grafana:

1. Add a new panel
2. Select the Heatmap visualization
3. Configure your query to return time series data
4. Adjust the Y-Buckets settings to control histogram buckets

Comparing Multiple Histograms​

To compare distributions across different metrics or time periods:

1. Create a new panel with Histogram visualization 
2. Add multiple queries for the different metrics you want to compare
3. In the display options, choose "opacity" or "transparent" to make overlapping bars visible

This approach helps identify differences in patterns between datasets.

Practical Examples​

Let's explore some real-world applications of histograms in monitoring and observability.

Example 1: Monitoring Application Performance​

For a web application, you might want to analyze response times to identify performance issues:

// Prometheus query example
rate(http_request_duration_seconds_bucket{job="api-server"}[5m])

Setting up a histogram panel with this query lets you:

  • Identify if most requests are within acceptable response time limits
  • Spot outliers that might indicate problems
  • Track changes in performance patterns over time

Example 2: Database Query Analysis​

For database monitoring, histograms can help analyze query execution times:

// SQL query for PostgreSQL query times (example)
SELECT le, count FROM pg_query_execution_time_histogram 
WHERE timestamp > now() - INTERVAL '30 minutes'

This visualization can help:

  • Identify slow queries that need optimization
  • Establish performance baselines
  • Detect changes after deployments or configuration updates

Best Practices for Using Histograms​

Choosing the Right Bin Size​

The bin size significantly impacts the insights you get from a histogram:

  • Too few bins (large bin size): Might hide important patterns (underfitting)
  • Too many bins (small bin size): Can introduce noise and make patterns hard to see (overfitting)

A good rule of thumb is to start with the square root of the number of data points as the number of bins, then adjust based on what looks clearest.

Logarithmic Scales​

For data with wide ranges or exponential patterns, consider using logarithmic scales:

1. In the panel options, find the Axis tab
2. Set the Y-axis scale to "logarithmic"

This helps visualize data that spans multiple orders of magnitude.

Context with Percentile Lines​

Adding percentile lines to your histogram can provide additional context:

1. Add a new threshold line in the panel options
2. Set it to represent your 95th or 99th percentile

This helps identify outliers and establish performance objectives.

Summary​

Histograms are powerful visualization tools in Grafana that help you understand the distribution and patterns in your data. They provide insights that aren't visible in simple averages or line charts.

Key takeaways:

  • Histograms group data into bins to show distribution patterns
  • They help identify normal behavior, outliers, and multi-modal patterns
  • Grafana offers multiple ways to create and customize histograms
  • Understanding distribution patterns helps with performance analysis and capacity planning

Exercises​

  1. Create a histogram showing the distribution of request durations for your application
  2. Experiment with different bin sizes to see how they affect the visualization
  3. Set up a dashboard with both a time series and histogram view of the same metric
  4. Create a heatmap to track how a distribution changes over the course of a day

Additional Resources​


If you spot any mistakes on this website, please let me know at [email protected]. I’d greatly appreciate your feedback! :)