histogram

This page explains how to use the histogram aggregation function in APL.

The histogram aggregation in APL allows you to create a histogram that groups numeric values into intervals or “bins.” This is useful for visualizing the distribution of data, such as the frequency of response times, request durations, or other continuous numerical fields. You can use it to analyze patterns and trends in datasets like logs, traces, or metrics. It is especially helpful when you need to summarize a large volume of data into a digestible form, providing insights on the distribution of values.

The histogram aggregation is ideal for identifying peaks, valleys, and outliers in your data. For example, you can analyze the distribution of request durations in web server logs or span durations in OpenTelemetry traces to understand performance bottlenecks.

For users of other query languages

If you come from other query languages, this section explains how to adjust your existing queries to achieve the same results in APL.

Splunk SPL users

In Splunk SPL, a similar operation to APL’s histogram is the timechart or histogram command, which groups events into time buckets. However, in APL, the histogram function focuses on numeric values, allowing you to control the bin size and boundaries more precisely.

ANSI SQL users

In ANSI SQL, you can use the GROUP BY clause combined with range calculations to achieve a similar result to APL’s histogram. However, APL’s histogram function simplifies the process by automatically calculating bin intervals.

Usage

Syntax

histogram(numeric_field, bin_size)

Parameters

• numeric_field: The numeric field you want to create a histogram for. This can be a field like request duration or span duration.
• bin_size: The size of each bin, or interval, into which the numeric values will be grouped.

Returns

The histogram aggregation returns a table where each row represents a bin, along with the number of occurrences (counts) that fall within each bin.

Use case examples

• Log analysis
• OpenTelemetry traces
• Security logs

You can use the histogram aggregation to analyze the distribution of request durations in web server logs.

Query

['sample-http-logs']
| summarize histogram(req_duration_ms, 100) by bin_auto(_time)

Run in Playground

Output

req_duration_ms_bin	count
0	50
100	200
200	120

This query creates a histogram that groups request durations into bins of 100 milliseconds and shows the count of requests in each bin. It helps you visualize how frequently requests fall within certain duration ranges.

List of related aggregations

• percentile: Use percentile when you need to find the specific value below which a percentage of observations fall, which can provide more precise distribution analysis.
• avg: Use avg for calculating the average value of a numeric field, useful when you are more interested in the central tendency rather than distribution.
• sum: The sum function adds up the total values in a numeric field, helpful for determining overall totals.
• count: Use count when you need a simple tally of rows or events, often in conjunction with histogram for more basic summarization.