Documentation

Flux

Work with Prometheus histograms

Use Flux to query and transform Prometheus histogram metrics stored in InfluxDB.

A histogram samples observations (usually things like request durations or response sizes) and counts them in configurable buckets. It also provides a sum of all observed values.

Prometheus metric types

Example histogram metric in Prometheus data
# HELP example_histogram_duration Duration of given tasks as example histogram metric
# TYPE example_histogram_duration histogram
example_histogram_duration_bucket{le="0.1"} 80
example_histogram_duration_bucket{le="0.25"} 85
example_histogram_duration_bucket{le="0.5"} 85
example_histogram_duration_bucket{le="1"} 87
example_histogram_duration_bucket{le="2.5"} 87
example_histogram_duration_bucket{le="5"} 88
example_histogram_duration_bucket{le="+Inf"} 88
example_histogram_duration_sum 6.833441910000001
example_histogram_duration_count 88

The examples below include example data collected from the InfluxDB OSS 2.x /metrics endpoint and stored in InfluxDB.

Prometheus metric parsing formats

Query structure depends on the Prometheus metric parsing format used to scrape the Prometheus metrics. Select the appropriate metric format version below.

Visualize Prometheus histograms in InfluxDB

InfluxDB does not currently support visualizing Prometheus histogram metrics as a traditional histogram. The existing InfluxDB histogram visualization is not compatible with the format of Prometheus histogram data stored in InfluxDB.

Calculate quantile values from Prometheus histograms

Metric version 2 Metric version 1

  1. Import the experimental/prometheus package.
  2. Filter results by the prometheus measurement and histogram metric name field.
  3. (Recommended) Use aggregateWindow() to downsample data and optimize the query.
  4. Use prometheus.histogramQuantile() to calculate a specific quantile.
import "experimental/prometheus"

from(bucket: "example-bucket")
    |> start(range: -1h)
    |> filter(fn: (r) => r._measurement == "prometheus")
    |> filter(fn: (r) => r._field == "qc_all_duration_seconds")
    |> aggregateWindow(every: 1m, fn: mean, createEmpty: false)
    |> prometheus.histogramQuantile(quantile: 0.99)
  1. Import the experimental/prometheus package.
  2. Filter results by the histogram metric name measurement.
  3. (Recommended) Use aggregateWindow() to downsample data and optimize the query. Set the createEmpty parameter to false.
  4. Use prometheus.histogramQuantile() to calculate a specific quantile. Specify the metricVersion as 1.
import "experimental/prometheus"

from(bucket: "example-bucket")
    |> start(range: -1h)
    |> filter(fn: (r) => r._measurement == "qc_all_duration_seconds")
    |> aggregateWindow(every: 1m, fn: mean, createEmpty: false)
    |> prometheus.histogramQuantile(quantile: 0.99, metricVersion: 1)
Calculate a quantile from Prometheus histogram metrics

Set createEmpty to false

When using aggregateWindow() to downsample data for prometheus.histogramQuantile, set the createEmpty parameter to false. Empty tables produced from aggregateWindow() result in the following error.

histogramQuantile: unexpected null in the countColumn

Calculate multiple quantiles from Prometheus histograms

  1. Query histogram data using steps 1-2 (optionally 3) from above.
  2. Use union() to union multiple streams of tables that calculate unique quantiles.

Metric version 2 Metric version 1

import "experimental/prometheus"

data =
    from(bucket: "example-bucket")
        |> start(range: -1h)
        |> filter(fn: (r) => r._measurement == "prometheus")
        |> filter(fn: (r) => r._field == "qc_all_duration_seconds")
        |> aggregateWindow(every: 1m, fn: mean, createEmpty: false)

union(
    tables: [
        data |> prometheus.histogramQuantile(quantile: 0.99),
        data |> prometheus.histogramQuantile(quantile: 0.5),
        data |> prometheus.histogramQuantile(quantile: 0.25),
    ],
)
import "experimental/prometheus"

data =
    from(bucket: "example-bucket")
        |> start(range: -1h)
        |> filter(fn: (r) => r._measurement == "qc_all_duration_seconds")
        |> aggregateWindow(every: 1m, fn: mean, createEmpty: false)

union(
    tables: [
        data |> prometheus.histogramQuantile(quantile: 0.99, metricVersion: 1),
        data |> prometheus.histogramQuantile(quantile: 0.5, metricVersion: 1),
        data |> prometheus.histogramQuantile(quantile: 0.25, metricVersion: 1),
    ],
)
Calculate multiple quantiles from Prometheus histogram metrics
prometheus

Was this page helpful?

Thank you for your feedback!

© 2025 InfluxData, Inc.

Where are you running InfluxDB?

Select your InfluxDB Cloud region and cluster or your InfluxDB OSS URL and we’ll customize code examples for you. Identify your InfluxDB Cloud cluster.

  • InfluxDB Cloud
  • InfluxDB OSS or Enterprise
AWS

  • US West (Oregon)

GCP
Azure
Default
Custom

For more information, see InfluxDB Cloud regions or InfluxDB OSS URLs.

Thank you for your feedback!

Let us know what we can do better:

Thank you!

No thanks

New in InfluxDB 3.5

Key enhancements in InfluxDB 3.5 and the InfluxDB 3 Explorer 1.3.

See the Blog Post

InfluxDB 3.5 is now available for both Core and Enterprise, introducing custom plugin repository support, enhanced operational visibility with queryable CLI parameters and manual node management, stronger security controls, and general performance improvements.

InfluxDB 3 Explorer 1.3 brings powerful new capabilities including Dashboards (beta) for saving and organizing your favorite queries, and cache querying for instant access to Last Value and Distinct Value caches—making Explorer a more comprehensive workspace for time series monitoring and analysis.

For more information, check out:

InfluxDB Docker latest tag changing to InfluxDB 3 Core

On November 3, 2025, the latest tag for InfluxDB Docker images will point to InfluxDB 3 Core. To avoid unexpected upgrades, use specific version tags in your Docker deployments.

If using Docker to install and run InfluxDB, the latest tag will point to InfluxDB 3 Core. To avoid unexpected upgrades, use specific version tags in your Docker deployments. For example, if using Docker to run InfluxDB v2, replace the latest version tag with a specific version tag in your Docker pull command–for example:

docker pull influxdb:2