From e0a9945eff83f28fafa9f87dbaec2188ea3cfd2d Mon Sep 17 00:00:00 2001 From: Adam Goode Date: Sun, 8 Sep 2024 00:31:09 -0400 Subject: [PATCH] prometheus: Document new config attribute `export_unavailable_metrics` --- source/_integrations/prometheus.markdown | 28 +++++++++++++++++++++++- 1 file changed, 27 insertions(+), 1 deletion(-) diff --git a/source/_integrations/prometheus.markdown b/source/_integrations/prometheus.markdown index 8fa1bb1287f5..742b803e1cb8 100644 --- a/source/_integrations/prometheus.markdown +++ b/source/_integrations/prometheus.markdown @@ -69,6 +69,11 @@ override_metric: type: string description: Metric name to use instead of unit or default metric. This will store all data points in a single metric. required: false +export_unavailable_metrics: + type: boolean + description: When true, metrics are continued to be exported when unavailable or unknown. If set to false, metrics will stop being exported when unavailable or unknown, and will export again when available and known. See [Metrics in unavailable or unknown states](#metrics-in-unavailable-or-unknown-states) for more details. + required: false + default: true component_config: type: string required: false @@ -130,6 +135,7 @@ Advanced configuration example: # Advanced configuration.yaml entry prometheus: namespace: hass + export_unavailable_metrics: false component_config_glob: sensor.*_hum: override_metric: humidity_percent @@ -194,7 +200,17 @@ Typically, you will only be interested in the first set of metrics. ## Metrics in unavailable or unknown states -When the Prometheus exporter starts (typically when Home Assistant starts), all non-excluded entities in an unavailable or unknown state are not be exported until they are available again. If the entity goes into state unavailable or unknown again, the value exported will always be the latest known one. +When the Prometheus exporter starts (typically when Home Assistant starts), all non-excluded entities in an unavailable or unknown state are not exported until they are available again. + +If the entity goes into state unavailable or unknown again, two things can happen depending on the state of the `export_unavailable_metrics` configuration attribute. + +{% note %} +The default value of `export_unavailable_metrics` will be switching from `true` to `false` in early 2025. +{% endnote %} + +### `export_unavailable_metrics: true` + +When `export_unavailable_metrics` is true (the default), the value exported will always be the latest known one. While an entity is in those states, the `entity_available` corresponding metric is set to 0. This metric can be used to filter out values while the entity is unavailable or in an unknown state thanks to a [recording rule](https://prometheus.io/docs/prometheus/latest/configuration/recording_rules/). @@ -205,6 +221,16 @@ For example: expr: "temperature_c unless entity_available == 0" ``` +### `export_unavailable_metrics: false` + +When `export_unavailable_metrics` is false, then metrics will automatically be unexported when unavailable or unknown, and return again automatically when available and known. This makes it possible to write simpler (and more often performant) queries since there is no need to use `unless entity_available == 0` or a recording rule to filter out these metrics. + +```yaml +# Example configuration.yaml entry +prometheus: + export_unavailable_metrics: false +``` + ## Supported metrics Metrics are exported only for the following domains: