Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: clarify native histograms visualization and mark as experimental #9776

Merged
merged 5 commits into from
Nov 8, 2024
Merged

docs: clarify native histograms visualization and mark as experimental #9776

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
e4730da
docs: clarify native histograms visualization and mark as experimental
krajorama Oct 30, 2024
8f6b8d6
clarify more
krajorama Oct 30, 2024
ed65451
Updates from review comments
krajorama Oct 30, 2024
a17ee15
is to are
krajorama Oct 30, 2024
8b485dc
Apply suggestions from code review
krajorama Nov 8, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion ...elm-charts/mimir-distributed/configure/configure-native-histograms-ingestion.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,7 +22,7 @@ mimir:
```

{{% admonition type="note" %}}
Native histograms is an experimental feature of Grafana Mimir.
Native histograms are an experimental feature of Grafana Mimir.
{{% /admonition %}}

To configure bucket limits for native histograms, refer to [Configure native histograms](https://grafana.com/docs/mimir/<MIMIR_VERSION>/configure/configure-native-histograms-ingestion/).
Expand Down
4 changes: 3 additions & 1 deletion docs/sources/mimir/configure/configure-native-histograms-ingestion.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,9 @@ weight: 160

# Configure native histograms

Prometheus native histograms ingestion is an experimental feature of Grafana Mimir.
{{% admonition type="note" %}}
Native histograms are an experimental feature of Grafana Mimir.
{{% /admonition %}}

You can configure native histograms ingestion via the Prometheus [remote write API]({{< relref "../references/http-api#remote-write" >}}) endpoint globally or per tenant.

Expand Down
4 changes: 4 additions & 0 deletions docs/sources/mimir/send/native-histograms/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,10 @@ weight: 100

# Send native histograms to Mimir

{{% admonition type="note" %}}
Native histograms are an experimental feature of Grafana Mimir.
{{% /admonition %}}

Prometheus native histograms is a data type in the Prometheus ecosystem that makes it possible to produce, store, and query a high-resolution [histogram](https://prometheus.io/docs/concepts/metric_types/#histogram) of observations.

Native histograms are different from classic Prometheus histograms in a number of ways:
Expand Down
4 changes: 4 additions & 0 deletions docs/sources/mimir/send/otel-exponential-histograms/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,10 @@ weight: 200

# Send OpenTelemetry exponential histograms to Mimir

{{% admonition type="note" %}}
Sending OpenTelemetry exponential histograms is an experimental feature of Grafana Mimir.
{{% /admonition %}}

You can collect and send exponential histograms to Mimir with the OpenTelemetry Collector. OpenTelemetry [exponential histograms](https://opentelemetry.io/docs/specs/otel/metrics/data-model/#exponentialhistogram) are compatible with Prometheus native histograms. The key difference is that exponential histograms store the `min` and `max` observation values explicitly, whereas native histograms don't. This means that for exponential histograms, you don't need to estimate these values using the 0.0 and 1.0 quantiles.

The OpenTelemetry Collector supports collecting exponential histograms and other compatible data formats, including native histograms and Datadog sketches, through its receivers and sending them through its exporters.
Expand Down
31 changes: 25 additions & 6 deletions docs/sources/mimir/visualize/native-histograms/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,17 +15,28 @@ weight: 100

# Visualize native histograms

Prometheus native histograms is a data type in the Prometheus ecosystem that makes it possible to produce, store, and query a high-resolution [histogram](https://prometheus.io/docs/concepts/metric_types/#histogram) of observations.
{{% admonition type="note" %}}
Native histograms are an experimental feature of Grafana Mimir.
{{% /admonition %}}

Prometheus native histograms are a data type in the Prometheus ecosystem that allow you to produce, store, and query a high-resolution [histogram](https://prometheus.io/docs/concepts/metric_types/#histogram) of observations.
To learn more about the native histograms data type and how to start sending native histograms to Grafana Mimir,
refer to [Send native histograms to Mimir]({{< relref "../../send/native-histograms" >}}).

{{% admonition type="note" %}}
Not all visualizations support the native histogram data type. However, you can use the Prometheus Query Language (PromQL) to derive the floating point time series from a native histogram, and then use this series in a visualization.
{{% /admonition %}}

## Prometheus Query Language

The Prometheus Query Language (PromQL) allows you to query native histogram metrics.
PromQL queries of native histograms are different from those of classic histograms.
Use the Prometheus Query Language (PromQL) to query native histogram metrics. The data type of your query results depends on the query and the underlying data.

For more information about PromQL, refer to [Querying Prometheus](https://prometheus.io/docs/prometheus/latest/querying/basics/).

The following examples show common ways to derive floating point data type from native histograms data for visualizations and also how to convert existing queries using classic histograms into queries using native histograms.

Note that the native histogram queries do not include the `_bucket`, `_sum` and `_count` suffixes of classic histograms.

### Query your histogram’s count or sum

To query the total count of observations within a histogram, use the following queries:
Expand Down Expand Up @@ -104,10 +115,18 @@ In that case, the current value is an accumulated value over the lifespan of the

## Create Grafana dashboards

When creating a Grafana dashboard for your native histogram, the most relevant panel types are [Histogram](/docs/grafana/latest/panels-visualizations/visualizations/histogram/) and [Heatmap](/docs/grafana/latest/panels-visualizations/visualizations/heatmap/).
The panel types [Histogram](/docs/grafana/latest/panels-visualizations/visualizations/histogram/) and [Heatmap](/docs/grafana/latest/panels-visualizations/visualizations/heatmap/) are compatible with the native histogram data type. Use these panel types to visualize a query, such as:

```PromQL
sum(rate(request_duration_seconds[$__rate_interval]))
```

For all other panel types, for example [Timeseries](/docs/grafana/latest/panels-visualizations/visualizations/time-series/), use one of the histogram functions in the [Prometheus Query Language](#prometheus-query-language) to visualize a derived float time series.

## Grafana classic explore

In [Explore](https://grafana.com/docs/grafana/latest/explore/), the functions `histogram_count`, `histogram_sum`, and `histogram_quantile` will result in normal floating point series that you can plot as usual.
In [Explore](https://grafana.com/docs/grafana/latest/explore/), use one of the histogram functions in [Prometheus Query Language](#prometheus-query-language) to visualize a derived float time series.

{{% admonition type="note" %}}
Visualizing native histogram series directly in the **Explore** view is a work in progress.
Visualizing native histogram data type directly without the histogram functions in the **Explore** view is not supported at this time.
{{% /admonition %}}
Loading