prometheus: Document new config attribute export_unavailable_metrics

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: