From 2c52fe63269d84280d4b7d54b5bcaf1cfd373a29 Mon Sep 17 00:00:00 2001 From: mdegat01 Date: Wed, 24 Jun 2020 08:25:22 -0400 Subject: [PATCH] Update doc for glob filter support (#13799) Co-authored-by: Franck Nijhof --- .../_integrations/alexa.smart_home.markdown | 49 +++--- source/_integrations/apache_kafka.markdown | 52 ++++++- source/_integrations/azure_event_hub.markdown | 57 ++++++- source/_integrations/google_pubsub.markdown | 53 ++++++- source/_integrations/homekit.markdown | 33 ++-- source/_integrations/logbook.markdown | 58 ++++++- .../_integrations/mqtt_statestream.markdown | 145 +++++++++++------- source/_integrations/prometheus.markdown | 55 ++++++- source/_integrations/recorder.markdown | 62 +++++++- source/_integrations/splunk.markdown | 50 +++++- 10 files changed, 519 insertions(+), 95 deletions(-) diff --git a/source/_integrations/alexa.smart_home.markdown b/source/_integrations/alexa.smart_home.markdown index 05953dd2669..dac9e8ca1b1 100644 --- a/source/_integrations/alexa.smart_home.markdown +++ b/source/_integrations/alexa.smart_home.markdown @@ -228,6 +228,8 @@ alexa: include_entities: - light.kitchen - light.kitchen_left + include_entity_globs: + - binary_sensor.*_motion include_domains: - switch exclude_entities: @@ -273,7 +275,7 @@ alexa: required: false type: string filter: - description: Filter domains and entities for Alexa. + description: Filter domains and entities for Alexa. ([Configure Filter](#configure-filter)) required: true type: map keys: @@ -285,6 +287,14 @@ alexa: description: List of domains to exclude (e.g., `light`). required: false type: list + include_entity_globs: + description: Include all entities matching a listed pattern (e.g., `binary_sensor.*_motion`). + required: false + type: list + exclude_entity_globs: + description: Exclude all entities matching a listed pattern (e.g., `binary_sensor.*_motion`). + required: false + type: list include_entities: description: List of entities to include (e.g., `light.attic`). required: false @@ -356,13 +366,15 @@ By default, no entity will be excluded. To limit which entities are being expose ```yaml # Example filter to include specified domains and exclude specified entities alexa: - smart_home: - filter: - include_domains: - - alarm_control_panel - - light - exclude_entities: - - light.kitchen_light + smart_home: + filter: + include_domains: + - alarm_control_panel + - light + include_entity_globs: + - binary_sensor.*_occupancy + exclude_entities: + - light.kitchen_light ``` {% endraw %} @@ -373,16 +385,17 @@ Filters are applied as follows: 2. Includes, no excludes - only include specified entities 3. Excludes, no includes - only exclude specified entities 4. Both includes and excludes: - - Include domain specified - - if domain is included, and entity not excluded, pass - - if domain is not included, and entity not included, fail - - Exclude domain specified - - if domain is excluded, and entity not included, fail - - if domain is not excluded, and entity not excluded, pass - - if both include and exclude domains specified, the exclude domains are ignored - - Neither include or exclude domain specified - - if entity is included, pass (as #2 above) - - if entity include and exclude, the entity exclude is ignored + - Include domain and/or glob patterns specified + - If domain is included, and entity not excluded or match exclude glob pattern, pass + - If entity matches include glob pattern, and entity does not match any exclude criteria (domain, glob pattern or listed), pass + - If domain is not included, glob pattern does not match, and entity not included, fail + - Exclude domain and/or glob patterns specified and include does not list domains or glob patterns + - If domain is excluded and entity not included, fail + - If entity matches exclude glob pattern and entity not included, fail + - If entity does not match any exclude criteria (domain, glob pattern or listed), pass + - Neither include or exclude specifies domains or glob patterns + - If entity is included, pass (as #2 above) + - If entity include and exclude, the entity exclude is ignored See the [troubleshooting](#troubleshooting) if for issues setting up the integration. diff --git a/source/_integrations/apache_kafka.markdown b/source/_integrations/apache_kafka.markdown index 44687803aee..a8982e860ac 100644 --- a/source/_integrations/apache_kafka.markdown +++ b/source/_integrations/apache_kafka.markdown @@ -39,7 +39,7 @@ topic: required: true type: string filter: - description: Filters for entities to be included/excluded. + description: Filters for entities to be included/excluded. ([Configure Filter](#configure-filter)) required: false type: map keys: @@ -47,6 +47,10 @@ filter: description: Domains to be included. required: false type: list + include_entity_globs: + description: Include all entities matching a listed pattern. + required: false + type: list include_entities: description: Entities to be included. required: false @@ -55,8 +59,54 @@ filter: description: Domains to be excluded. required: false type: list + exclude_entity_globs: + description: Exclude all entities matching a listed pattern. + required: false + type: list exclude_entities: description: Entities to be excluded. required: false type: list {% endconfiguration %} + +## Configure Filter + +By default, no entity will be excluded. To limit which entities are being exposed to `Apache Kafka`, you can use the `filter` parameter. + +{% raw %} + +```yaml +# Example filter to include specified domains and exclude specified entities +apache_kafka: + ip_address: localhost + port: 9092 + topic: home_assistant_1 + filter: + include_domains: + - alarm_control_panel + - light + include_entity_globs: + - binary_sensor.*_occupancy + exclude_entities: + - light.kitchen_light +``` + +{% endraw %} + +Filters are applied as follows: + +1. No includes or excludes - pass all entities +2. Includes, no excludes - only include specified entities +3. Excludes, no includes - only exclude specified entities +4. Both includes and excludes: + - Include domain and/or glob patterns specified + - If domain is included, and entity not excluded or match exclude glob pattern, pass + - If entity matches include glob pattern, and entity does not match any exclude criteria (domain, glob pattern or listed), pass + - If domain is not included, glob pattern does not match, and entity not included, fail + - Exclude domain and/or glob patterns specified and include does not list domains or glob patterns + - If domain is excluded and entity not included, fail + - If entity matches exclude glob pattern and entity not included, fail + - If entity does not match any exclude criteria (domain, glob pattern or listed), pass + - Neither include or exclude specifies domains or glob patterns + - If entity is included, pass (as #2 above) + - If entity include and exclude, the entity exclude is ignored diff --git a/source/_integrations/azure_event_hub.markdown b/source/_integrations/azure_event_hub.markdown index 592bfce2a8d..d928206d95d 100644 --- a/source/_integrations/azure_event_hub.markdown +++ b/source/_integrations/azure_event_hub.markdown @@ -75,7 +75,7 @@ max_delay: type: integer default: 30 filter: - description: Filter domains and entities for Event Hub. + description: Filter domains and entities for Event Hub. ([Configure Filter](#configure-filter)) required: true type: map default: Includes all entities from all domains @@ -88,6 +88,14 @@ filter: description: List of domains to exclude (e.g., `light`). required: false type: list + include_entity_globs: + description: Include all entities matching a listed pattern (e.g., `sensor.weather_*`). + required: false + type: list + exclude_entity_globs: + description: Exclude all entities matching a listed pattern (e.g., `sensor.weather_*`). + required: false + type: list include_entities: description: List of entities to include (e.g., `light.attic`). required: false @@ -99,16 +107,59 @@ filter: {% endconfiguration %}
-Not filtering domains or entities will send every event to Azure Event Hub, thus taking up a lot of space. +Not filtering domains or entities will send every event to Azure Event Hub, thus taking up a lot of space.
Event Hubs have a retention time of at most 7 days, if you do not capture or use the events they are deleted automatically from the Event Hub, the default retention is 1 day.
+### Configure Filter + +By default, no entity will be excluded. To limit which entities are being exposed to `Azure Event Hub`, you can use the `filter` parameter. + +{% raw %} + +```yaml +# Example filter to include specified domains and exclude specified entities +azure_event_hub: + event_hub_namespace: NAMESPACE_NAME + event_hub_instance_name: EVENT_HUB_INSTANCE_NAME + event_hub_sas_policy: SAS_POLICY_NAME + event_hub_sas_key: SAS_KEY + filter: + include_domains: + - alarm_control_panel + - light + include_entity_globs: + - binary_sensor.*_occupancy + exclude_entities: + - light.kitchen_light +``` + +{% endraw %} + +Filters are applied as follows: + +1. No includes or excludes - pass all entities +2. Includes, no excludes - only include specified entities +3. Excludes, no includes - only exclude specified entities +4. Both includes and excludes: + - Include domain and/or glob patterns specified + - If domain is included, and entity not excluded or match exclude glob pattern, pass + - If entity matches include glob pattern, and entity does not match any exclude criteria (domain, glob pattern or listed), pass + - If domain is not included, glob pattern does not match, and entity not included, fail + - Exclude domain and/or glob patterns specified and include does not list domains or glob patterns + - If domain is excluded and entity not included, fail + - If entity matches exclude glob pattern and entity not included, fail + - If entity does not match any exclude criteria (domain, glob pattern or listed), pass + - Neither include or exclude specifies domains or glob patterns + - If entity is included, pass (as #2 above) + - If entity include and exclude, the entity exclude is ignored + ### Advanced configuration -This is what the configuration will look like when using a connection string directly, instead of the four parameters. It also shows how to set the send_interval and max_delay to something other than the default. This means once every minute the integration will connect to your hub and send messages, but the messages have to be less than 65 seconds old at the time of sending for them to be counted (send_interval + max_delay). +This is what the configuration will look like when using a connection string directly, instead of the four parameters. It also shows how to set the send_interval and max_delay to something other than the default. This means once every minute the integration will connect to your hub and send messages, but the messages have to be less than 65 seconds old at the time of sending for them to be counted (send_interval + max_delay). ```yaml # Connection string config with non-defaults for send_interval and max_delay diff --git a/source/_integrations/google_pubsub.markdown b/source/_integrations/google_pubsub.markdown index 5dd29729d84..35431fc696e 100644 --- a/source/_integrations/google_pubsub.markdown +++ b/source/_integrations/google_pubsub.markdown @@ -14,6 +14,7 @@ The `google_pubsub` integration allows you to hook into the Home Assistant event This assumes you already have a Google Cloud project. If you don't, please create one in the [Google Cloud Console](https://console.cloud.google.com/projectcreate) You need to create a Service Account key in the [Google Cloud API Console](https://console.cloud.google.com/apis/credentials/serviceaccountkey) + - Choose a new "New Service Account", give it a name and leave the key type as JSON - Select the role: Pub/Sub Publisher @@ -48,7 +49,7 @@ credentials_json: required: true type: string filter: - description: Filter domains and entities for Google Cloud Pub/Sub. + description: Filter domains and entities for Google Cloud Pub/Sub. ([Configure Filter](#configure-filter)) required: true type: map keys: @@ -60,6 +61,14 @@ filter: description: List of domains to exclude (e.g., `light`). required: false type: list + include_entity_globs: + description: Include all entities matching a listed pattern (e.g., `sensor.weather_*`). + required: false + type: list + exclude_entity_globs: + description: Exclude all entities matching a listed pattern (e.g., `sensor.weather_*`). + required: false + type: list include_entities: description: List of entities to include (e.g., `light.attic`). required: false @@ -74,6 +83,48 @@ filter: Not filtering domains or entities will send every event to Google PubSub, thus hitting the free tier limit very fast. Be sure to fill in this configuration parameter or have a paid subscription for Google Cloud. +### Configure Filter + +By default, no entity will be excluded. To limit which entities are being exposed to `Google Pub/Sub`, you can use the `filter` parameter. + +{% raw %} + +```yaml +# Example filter to include specified domains and exclude specified entities +google_pubsub: + project_id: YOUR_PROJECT_ID + topic_name: YOUR_TOPIC_NAME + credentials_json: CREDENTIALS_FILENAME + filter: + include_domains: + - alarm_control_panel + - light + include_entity_globs: + - binary_sensor.*_occupancy + exclude_entities: + - light.kitchen_light +``` + +{% endraw %} + +Filters are applied as follows: + +1. No includes or excludes - pass all entities +2. Includes, no excludes - only include specified entities +3. Excludes, no includes - only exclude specified entities +4. Both includes and excludes: + - Include domain and/or glob patterns specified + - If domain is included, and entity not excluded or match exclude glob pattern, pass + - If entity matches include glob pattern, and entity does not match any exclude criteria (domain, glob pattern or listed), pass + - If domain is not included, glob pattern does not match, and entity not included, fail + - Exclude domain and/or glob patterns specified and include does not list domains or glob patterns + - If domain is excluded and entity not included, fail + - If entity matches exclude glob pattern and entity not included, fail + - If entity does not match any exclude criteria (domain, glob pattern or listed), pass + - Neither include or exclude specifies domains or glob patterns + - If entity is included, pass (as #2 above) + - If entity include and exclude, the entity exclude is ignored + ### Saving the data using a Google Cloud Function To save your data automatically to BigQuery, follow the [instructions here](https://github.com/timvancann/home-assistant-pubsub-cloud-function). The current [free tier](https://cloud.google.com/free/) of GCP should allow to store up to 10GB of data. diff --git a/source/_integrations/homekit.markdown b/source/_integrations/homekit.markdown index 57316d9926e..9526edd0359 100644 --- a/source/_integrations/homekit.markdown +++ b/source/_integrations/homekit.markdown @@ -31,6 +31,8 @@ homekit: - alarm_control_panel - light - media_player + include_entity_globs: + - binary_sensor.*_occupancy include_entities: - binary_sensor.living_room_motion entity_config: @@ -103,6 +105,10 @@ homekit: description: Domains to be included. required: false type: list + include_entity_globs: + description: Include all entities matching a listed pattern (e.g., `binary_sensor.*_motion`). + required: false + type: list include_entities: description: Entities to be included. required: false @@ -111,6 +117,10 @@ homekit: description: Domains to be excluded. required: false type: list + exclude_entity_globs: + description: Exclude all entities matching a listed pattern (e.g., `sensor.*_motion`). + required: false + type: list exclude_entities: description: Entities to be excluded. required: false @@ -371,6 +381,8 @@ homekit: include_domains: - alarm_control_panel - light + include_entity_globs: + - binary_sensor.*_occupancy exclude_entities: - light.kitchen_light ``` @@ -383,16 +395,17 @@ Filters are applied as follows: 2. Includes, no excludes - only include specified entities 3. Excludes, no includes - only exclude specified entities 4. Both includes and excludes: - - Include domain specified - - if domain is included, and entity not excluded, pass - - if domain is not included, and entity not included, fail - - Exclude domain specified - - if domain is excluded, and entity not included, fail - - if domain is not excluded, and entity not excluded, pass - - if both include and exclude domains specified, the exclude domains are ignored - - Neither include or exclude domain specified - - if entity is included, pass (as #2 above) - - if entity include and exclude, the entity exclude is ignored + - Include domain and/or glob patterns specified + - If domain is included, and entity not excluded or match exclude glob pattern, pass + - If entity matches include glob pattern, and entity does not match any exclude criteria (domain, glob pattern or listed), pass + - If domain is not included, glob pattern does not match, and entity not included, fail + - Exclude domain and/or glob patterns specified and include does not list domains or glob patterns + - If domain is excluded and entity not included, fail + - If entity matches exclude glob pattern and entity not included, fail + - If entity does not match any exclude criteria (domain, glob pattern or listed), pass + - Neither include or exclude specifies domains or glob patterns + - If entity is included, pass (as #2 above) + - If entity include and exclude, the entity exclude is ignored ## Safe Mode diff --git a/source/_integrations/logbook.markdown b/source/_integrations/logbook.markdown index b718018d155..116805371f6 100644 --- a/source/_integrations/logbook.markdown +++ b/source/_integrations/logbook.markdown @@ -26,7 +26,7 @@ logbook: {% configuration %} exclude: - description: "Configure which integrations should **not** create logbook entries." + description: "Configure which integrations should **not** create logbook entries. ([Configure Filter](#configure-filter))" required: false type: map keys: @@ -34,12 +34,16 @@ exclude: description: The list of entity ids to be excluded from creating logbook entries. required: false type: list + entity_globs: + description: Exclude all entities matching a listed pattern from creating logbook entries (e.g., `sensor.weather_*`). + required: false + type: list domains: description: The list of domains to be excluded from creating logbook entries. required: false type: list include: - description: Configure which integrations should create logbook entries. + description: Configure which integrations should create logbook entries. ([Configure Filter](#configure-filter)) required: false type: map keys: @@ -47,12 +51,58 @@ include: description: The list of entity ids to be included in creating logbook entries. required: false type: list + entity_globs: + description: Include all entities matching a listed pattern when creating logbook entries (e.g., `sensor.weather_*`). + required: false + type: list domains: description: The list of domains to be included in creating logbook entries. required: false type: list {% endconfiguration %} +## Configure Filter + +By default, no entity will be excluded. To limit which entities are being exposed to `Logbook`, you can use the `include` and `exclude` parameters. + +{% raw %} + +```yaml +# Example filter to include specified domains and exclude specified entities +logbook: + include: + domains: + - alarm_control_panel + - light + entity_globs: + - binary_sensor.*_occupancy + exclude: + entities: + - light.kitchen_light +``` + +{% endraw %} + +Filters are applied as follows: + +1. No includes or excludes - pass all entities +2. Includes, no excludes - only include specified entities +3. Excludes, no includes - only exclude specified entities +4. Both includes and excludes: + - Include domain and/or glob patterns specified + - If domain is included, and entity not excluded or match exclude glob pattern, pass + - If entity matches include glob pattern, and entity does not match any exclude criteria (domain, glob pattern or listed), pass + - If domain is not included, glob pattern does not match, and entity not included, fail + - Exclude domain and/or glob patterns specified and include does not list domains or glob patterns + - If domain is excluded and entity not included, fail + - If entity matches exclude glob pattern and entity not included, fail + - If entity does not match any exclude criteria (domain, glob pattern or listed), pass + - Neither include or exclude specifies domains or glob patterns + - If entity is included, pass (as #2 above) + - If entity include and exclude, the entity exclude is ignored + +### Common filtering examples + If you want to exclude messages of some entities or domains from the logbook just add the `exclude` parameter like: @@ -63,6 +113,8 @@ logbook: entities: - sensor.last_boot - sensor.date + entity_globs: + - sensor.weather_* domains: - sun ``` @@ -96,6 +148,8 @@ logbook: entities: - sensor.last_boot - sensor.date + entity_globs: + - sensor.weather_* ``` ### Exclude Events diff --git a/source/_integrations/mqtt_statestream.markdown b/source/_integrations/mqtt_statestream.markdown index 15c27e6ce97..9eff9a93cdc 100644 --- a/source/_integrations/mqtt_statestream.markdown +++ b/source/_integrations/mqtt_statestream.markdown @@ -38,7 +38,7 @@ publish_timestamps: default: false type: boolean exclude: - description: Configure which integrations should be excluded from recordings. See *Include/Exclude* section below for details. + description: Configure which integrations should be excluded from recordings. ([Configure Filter](#configure-filter)) required: false type: list keys: @@ -46,12 +46,16 @@ exclude: description: The list of entity ids to be excluded from recordings. required: false type: list + entity_globs: + description: Exclude all entities matching a listed pattern from recordings (e.g., `sensor.weather_*`). + required: false + type: list domains: description: The list of domains to be excluded from recordings. required: false type: list include: - description: Configure which integrations should be included in recordings. If set, all other entities will not be recorded. + description: Configure which integrations should be included in recordings. If set, all other entities will not be recorded. ([Configure Filter](#configure-filter)) required: false type: list keys: @@ -59,12 +63,99 @@ include: description: The list of entity ids to be included from recordings. required: false type: list + entity_globs: + description: Include all entities matching a listed pattern in recordings (e.g., `sensor.weather_*`). + required: false + type: list domains: description: The list of domains to be included from recordings. required: false type: list {% endconfiguration %} +### Configure Filter + +By default, no entity will be excluded. To limit which entities are being exposed to `MQTT Statestream`, you can use the `include` and `exclude` parameters. + +{% raw %} + +```yaml +# Example filter to include specified domains and exclude specified entities +mqtt_statestream: + base_topic: homeassistant + include: + domains: + - alarm_control_panel + - light + entity_globs: + - binary_sensor.*_occupancy + exclude: + entities: + - light.kitchen_light +``` + +{% endraw %} + +Filters are applied as follows: + +1. No includes or excludes - pass all entities +2. Includes, no excludes - only include specified entities +3. Excludes, no includes - only exclude specified entities +4. Both includes and excludes: + - Include domain and/or glob patterns specified + - If domain is included, and entity not excluded or match exclude glob pattern, pass + - If entity matches include glob pattern, and entity does not match any exclude criteria (domain, glob pattern or listed), pass + - If domain is not included, glob pattern does not match, and entity not included, fail + - Exclude domain and/or glob patterns specified and include does not list domains or glob patterns + - If domain is excluded and entity not included, fail + - If entity matches exclude glob pattern and entity not included, fail + - If entity does not match any exclude criteria (domain, glob pattern or listed), pass + - Neither include or exclude specifies domains or glob patterns + - If entity is included, pass (as #2 above) + - If entity include and exclude, the entity exclude is ignored + +### Common filtering examples + +```yaml +# Example of excluding entities +mqtt_statestream: + base_topic: homeassistant + exclude: + domains: + - switch + entities: + - sensor.nopublish +``` + +In the above example, all entities except for *switch.x* and *sensor.nopublish* will be published to MQTT. + +```yaml +# Example of excluding entities +mqtt_statestream: + base_topic: homeassistant + include: + domains: + - sensor + entities: + - lock.important +``` + +In this example, only *sensor.x* and *lock.important* will be published. + +```yaml +# Example of excluding entities +mqtt_statestream: + base_topic: homeassistant + include: + domains: + - sensor + exclude: + entities: + - sensor.noshow +``` + +In this example, all sensors except for *sensor.noshow* will be published. + ## Operation When any Home Assistant entity changes, this integration will publish that change to MQTT. @@ -79,53 +170,3 @@ If that entity also has an attribute called `brightness`, the integration will a All states and attributes are passed through JSON serialization before publishing. **Please note** that this causes strings to be quoted (e.g., the string 'on' will be published as '"on"'). You can access the JSON deserialized values (as well as unquoted strings) at many places by using `value_json` instead of `value`. The last_updated and last_changed values for the entity will be published to `homeassistant/light/master_bedroom_dimmer/last_updated` and `homeassistant/light/master_bedroom_dimmer/last_changed`, respectively. The timestamps are in ISO 8601 format - for example, `2017-10-01T23:20:30.920969+00:00`. - -## Include/exclude - -The **exclude** and **include** configuration variables can be used to filter the items that are published to MQTT. - -1\. If neither **exclude** or **include** are specified, all entities are published. - -2\. If only **exclude** is specified, then all entities except the ones listed are published. - -```yaml -# Example of excluding entities -mqtt_statestream: - base_topic: homeassistant - exclude: - domains: - - switch - entities: - - sensor.nopublish -``` -In the above example, all entities except for *switch.x* and *sensor.nopublish* will be published to MQTT. - -3\. If only **include** is specified, then only the specified entries are published. - -```yaml -# Example of excluding entities -mqtt_statestream: - base_topic: homeassistant - include: - domains: - - sensor - entities: - - lock.important -``` -In this example, only *sensor.x* and *lock.important* will be published. - -4\. If both **include** and **exclude** are specified then all entities specified by **include** are published except for the ones -specified by **exclude**. - -```yaml -# Example of excluding entities -mqtt_statestream: - base_topic: homeassistant - include: - domains: - - sensor - exclude: - entities: - - sensor.noshow -``` -In this example, all sensors except for *sensor.noshow* will be published. diff --git a/source/_integrations/prometheus.markdown b/source/_integrations/prometheus.markdown index cc07f73ff6c..ec71f73a189 100644 --- a/source/_integrations/prometheus.markdown +++ b/source/_integrations/prometheus.markdown @@ -24,7 +24,7 @@ namespace: required: false type: string filter: - description: Filtering directives for the integrations which should be included or excluded from recording. + description: Filtering directives for the integrations which should be included or excluded from recording. ([Configure Filter](#configure-filter)) required: false type: list keys: @@ -32,6 +32,10 @@ filter: description: The list of entity ids to be excluded from recording. required: false type: list + exclude_entity_globs: + description: Exclude all entities matching a listed pattern (e.g., `sensor.weather_*`). + required: false + type: list exclude_domains: description: The list of domains to be excluded from recording. required: false @@ -40,13 +44,17 @@ filter: description: The list of entity ids to be included from recordings. If set, all other entities will not be recorded. Values set by the **exclude_*** option will prevail. required: false type: list + include_entity_globs: + description: Include all entities matching a listed pattern (e.g., `sensor.weather_*`). If set, all other entities will not be recorded. Values set by the **exclude_*** option will prevail. + required: false + type: list include_domains: description: The list of domains to be included from recordings. If set, all other entities will not be recorded. Values set by the **exclude_*** option will prevail. required: false type: list default_metric: type: string - description: Metric name to use when an entity doesn't have a unit. + description: Metric name to use when an entity doesn't have a unit. required: false default: uses the entity id of the entity override_metric: @@ -71,7 +79,7 @@ component_config_domain: 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 -component_config_glob: +component_config_glob: type: string required: false description: This attribute contains component-specific override values. See [Customizing devices and services](/getting-started/customizing-devices/) for format. @@ -83,6 +91,45 @@ component_config_glob: {% endconfiguration %} +### Configure Filter + +By default, no entity will be excluded. To limit which entities are being exposed to `Prometheus`, you can use the `filter` parameter. + +{% raw %} + +```yaml +# Example filter to include specified domains and exclude specified entities +prometheus: + filter: + include_domains: + - alarm_control_panel + - light + include_entity_globs: + - binary_sensor.*_occupancy + exclude_entities: + - light.kitchen_light +``` + +{% endraw %} + +Filters are applied as follows: + +1. No includes or excludes - pass all entities +2. Includes, no excludes - only include specified entities +3. Excludes, no includes - only exclude specified entities +4. Both includes and excludes: + - Include domain and/or glob patterns specified + - If domain is included, and entity not excluded or match exclude glob pattern, pass + - If entity matches include glob pattern, and entity does not match any exclude criteria (domain, glob pattern or listed), pass + - If domain is not included, glob pattern does not match, and entity not included, fail + - Exclude domain and/or glob patterns specified and include does not list domains or glob patterns + - If domain is excluded and entity not included, fail + - If entity matches exclude glob pattern and entity not included, fail + - If entity does not match any exclude criteria (domain, glob pattern or listed), pass + - Neither include or exclude specifies domains or glob patterns + - If entity is included, pass (as #2 above) + - If entity include and exclude, the entity exclude is ignored + ## Full Example Advanced configuration example: @@ -103,6 +150,8 @@ prometheus: filter: include_domains: - sensor + exclude_entity_globs: + - sensor.weather_* ``` You can then configure Prometheus to fetch metrics from Home Assistant by adding to its `scrape_configs` configuration. diff --git a/source/_integrations/recorder.markdown b/source/_integrations/recorder.markdown index 756b8117679..2f18f1d7b50 100644 --- a/source/_integrations/recorder.markdown +++ b/source/_integrations/recorder.markdown @@ -63,7 +63,7 @@ recorder: default: 1 type: integer exclude: - description: Configure which integrations should be excluded from recordings. + description: Configure which integrations should be excluded from recordings. ([Configure Filter](#configure-filter)) required: false type: map keys: @@ -71,6 +71,10 @@ recorder: description: The list of domains to be excluded from recordings. required: false type: list + entity_globs: + description: Exclude all entities matching a listed pattern from recordings (e.g., `sensor.weather_*`). + required: false + type: list entities: description: The list of entity ids to be excluded from recordings. required: false @@ -80,7 +84,7 @@ recorder: required: false type: list include: - description: Configure which integrations should be included in recordings. If set, all other entities will not be recorded. + description: Configure which integrations should be included in recordings. If set, all other entities will not be recorded. ([Configure Filter](#configure-filter)) required: false type: map keys: @@ -88,12 +92,60 @@ recorder: description: The list of domains to be included in the recordings. required: false type: list + entity_globs: + description: Include all entities matching a listed pattern from recordings (e.g., `sensor.weather_*`). + required: false + type: list entities: description: The list of entity ids to be included in the recordings. required: false type: list {% endconfiguration %} +## Configure Filter + +By default, no entity will be excluded. To limit which entities are being exposed to `Recorder`, you can use the `include` and `exclude` parameters. + +{% raw %} + +```yaml +# Example filter to include specified domains and exclude specified entities +recorder: + include: + domains: + - alarm_control_panel + - light + entity_globs: + - binary_sensor.*_occupancy + exclude: + entities: + - light.kitchen_light +``` + +{% endraw %} + +Filters are applied as follows: + +1. No includes or excludes - pass all entities +2. Includes, no excludes - only include specified entities +3. Excludes, no includes - only exclude specified entities +4. Both includes and excludes: + - Include domain and/or glob patterns specified + - If domain is included, and entity not excluded or match exclude glob pattern, pass + - If entity matches include glob pattern, and entity does not match any exclude criteria (domain, glob pattern or listed), pass + - If domain is not included, glob pattern does not match, and entity not included, fail + - Exclude domain and/or glob patterns specified and include does not list domains or glob patterns + - If domain is excluded and entity not included, fail + - If entity matches exclude glob pattern and entity not included, fail + - If entity does not match any exclude criteria (domain, glob pattern or listed), pass + - Neither include or exclude specifies domains or glob patterns + - If entity is included, pass (as #2 above) + - If entity include and exclude, the entity exclude is ignored + +If you only want to hide events from your history, take a look at the [`history` integration](/integrations/history/). The same goes for the [logbook](/integrations/logbook/). But if you have privacy concerns about certain events or want them in neither the history or logbook, you should use the `exclude`/`include` options of the `recorder` integration. That way they aren't even in your database, you can reduce storage and keep the database small by excluding certain often-logged events (like `sensor.last_boot`). + +### Common filtering examples + Defining domains and entities to `exclude` (i.e. blacklist) is convenient when you are basically happy with the information recorded, but just want to remove some entities or domains. ```yaml @@ -105,6 +157,8 @@ recorder: domains: - automation - updater + entity_globs: + - sensor.weather_* entities: - sun.sun # Don't record sun data - sensor.last_boot # Comes from 'systemmonitor' sensor platform @@ -139,10 +193,10 @@ recorder: entities: - sensor.last_boot - sensor.date + entity_globs: + - sensor.weather_* ``` -If you only want to hide events from your history, take a look at the [`history` integration](/integrations/history/). The same goes for the [logbook](/integrations/logbook/). But if you have privacy concerns about certain events or want them in neither the history or logbook, you should use the `exclude`/`include` options of the `recorder` integration. That way they aren't even in your database, you can reduce storage and keep the database small by excluding certain often-logged events (like `sensor.last_boot`). - ### Service `purge` Call the service `recorder.purge` to start a purge task which deletes events and states older than x days, according to `keep_days` service data. diff --git a/source/_integrations/splunk.markdown b/source/_integrations/splunk.markdown index be0ed9431e7..ebebf567b05 100644 --- a/source/_integrations/splunk.markdown +++ b/source/_integrations/splunk.markdown @@ -50,7 +50,7 @@ name: default: HASS type: string filter: - description: Filters for entities to be included/excluded from Splunk. Default is to include all entities. + description: Filters for entities to be included/excluded from Splunk. Default is to include all entities. ([Configure Filter](#configure-filter)) required: false type: map keys: @@ -58,6 +58,10 @@ filter: description: Domains to be included. required: false type: list + include_entity_globs: + description: Include all entities matching a listed pattern (e.g., `sensor.weather_*`). + required: false + type: list include_entities: description: Entities to be included. required: false @@ -66,8 +70,52 @@ filter: description: Domains to be excluded. required: false type: list + exclude_entity_globs: + description: Exclude all entities matching a listed pattern (e.g., `sensor.weather_*`). + required: false + type: list exclude_entities: description: Entities to be excluded. required: false type: list {% endconfiguration %} + +### Configure Filter + +By default, no entity will be excluded. To limit which entities are being exposed to `Splunk`, you can use the `filter` parameter. + +{% raw %} + +```yaml +# Example filter to include specified domains and exclude specified entities +splunk: + token: YOUR_SPLUNK_TOKEN + filter: + include_domains: + - alarm_control_panel + - light + include_entity_globs: + - binary_sensor.*_occupancy + exclude_entities: + - light.kitchen_light +``` + +{% endraw %} + +Filters are applied as follows: + +1. No includes or excludes - pass all entities +2. Includes, no excludes - only include specified entities +3. Excludes, no includes - only exclude specified entities +4. Both includes and excludes: + - Include domain and/or glob patterns specified + - If domain is included, and entity not excluded or match exclude glob pattern, pass + - If entity matches include glob pattern, and entity does not match any exclude criteria (domain, glob pattern or listed), pass + - If domain is not included, glob pattern does not match, and entity not included, fail + - Exclude domain and/or glob patterns specified and include does not list domains or glob patterns + - If domain is excluded and entity not included, fail + - If entity matches exclude glob pattern and entity not included, fail + - If entity does not match any exclude criteria (domain, glob pattern or listed), pass + - Neither include or exclude specifies domains or glob patterns + - If entity is included, pass (as #2 above) + - If entity include and exclude, the entity exclude is ignored