---
title: Work with Prometheus histograms
description: 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.
url: https://docs.influxdata.com/flux/v0/prometheus/metric-types/histogram/
estimated_tokens: 4970
product: Flux
version: v0
---

# 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](https://prometheus.io/docs/concepts/metric_types/#histogram)

##### Example histogram metric in Prometheus data

```sh
# 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](/influxdb/v2/reference/prometheus-metrics/) used to scrape the Prometheus metrics. Select the appropriate metric format version below.

-   [Calculate quantile values from Prometheus histograms](#calculate-quantile-values-from-prometheus-histograms)
-   [Calculate multiple quantiles from Prometheus histograms](#calculate-multiple-quantiles-from-prometheus-histograms)

## Visualize Prometheus histograms in InfluxDB

*InfluxDB does not currently support visualizing Prometheus histogram metrics as a traditional histogram. The existing [InfluxDB histogram visualization](/influxdb/cloud/visualize-data/visualization-types/histogram/) is **not compatible** with the format of Prometheus histogram data stored in InfluxDB.*

## Calculate quantile values from Prometheus histograms

<!-- Tabbed content: Select one of the following options -->

**Metric version 2:**

1. Import the [`experimental/prometheus` package](/flux/v0/stdlib/experimental/prometheus/).
2. Filter results by the `prometheus` measurement and **histogram metric name** field.
3. *(Recommended)* Use [`aggregateWindow()`](/flux/v0/stdlib/universe/aggregatewindow/) to downsample data and optimize the query.
4. Use [`prometheus.histogramQuantile()`](/flux/v0/stdlib/experimental/prometheus/histogramquantile/) to calculate a specific quantile.

```js
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)
```

**Metric version 1:**

1. Import the [`experimental/prometheus` package](/flux/v0/stdlib/experimental/prometheus/).
2. Filter results by the **histogram metric name** measurement.
3. *(Recommended)* Use [`aggregateWindow()`](/flux/v0/stdlib/universe/aggregatewindow/) to downsample data and optimize the query. **Set the `createEmpty` parameter to `false`.**
4. Use [`prometheus.histogramQuantile()`](/flux/v0/stdlib/experimental/prometheus/histogramquantile) to calculate a specific quantile. Specify the `metricVersion` as `1`.

```js
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)
```

<!-- End tabbed content -->
![Calculate a quantile from Prometheus histogram metrics](/img/flux/0-x-prometheus-histogram-quantile.png)

#### 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](#calculate-quantiles-from-prometheus-histograms).
2. Use [`union()`](/flux/v0/stdlib/universe/union/) to union multiple streams of tables that calculate unique quantiles.

<!-- Tabbed content: Select one of the following options -->

**Metric version 2:**

```js
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),
    ],
)
```

**Metric version 1:**

```js
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),
    ],
)
```

<!-- End tabbed content -->
![Calculate multiple quantiles from Prometheus histogram metrics](/img/flux/0-x-prometheus-histogram-multiple-quantiles.png)

#### Related

-   [Prometheus metric types](https://prometheus.io/docs/concepts/metric_types/)
-   [Prometheus metric parsing formats](/influxdb/v2/reference/prometheus-metrics/)
-   [prometheus.histogramQuantile() function](/flux/v0/stdlib/experimental/prometheus/histogramquantile/)

[prometheus](/flux/v0/tags/prometheus/)