From 0ff5142c840c348e976afe9cc54429b6081dac21 Mon Sep 17 00:00:00 2001 From: "J. Nick Koston" Date: Tue, 7 Jun 2022 00:25:48 -1000 Subject: [PATCH] Move description of how filtering works to an include (#22974) --- source/_includes/common-tasks/filters.md | 22 +++++++++++++++++++ .../_integrations/alexa.smart_home.markdown | 18 +-------------- source/_integrations/apache_kafka.markdown | 18 +-------------- source/_integrations/azure_event_hub.markdown | 18 +-------------- source/_integrations/google_pubsub.markdown | 18 +-------------- source/_integrations/history.markdown | 12 +--------- source/_integrations/homekit.markdown | 18 +-------------- source/_integrations/influxdb.markdown | 18 +-------------- source/_integrations/logbook.markdown | 12 +--------- .../_integrations/mqtt_statestream.markdown | 18 +-------------- source/_integrations/prometheus.markdown | 18 +-------------- source/_integrations/recorder.markdown | 18 +-------------- source/_integrations/splunk.markdown | 18 +-------------- source/_integrations/zabbix.markdown | 18 +-------------- 14 files changed, 35 insertions(+), 209 deletions(-) create mode 100644 source/_includes/common-tasks/filters.md diff --git a/source/_includes/common-tasks/filters.md b/source/_includes/common-tasks/filters.md new file mode 100644 index 00000000000..78e63b2f15a --- /dev/null +++ b/source/_includes/common-tasks/filters.md @@ -0,0 +1,22 @@ +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, accept + - If entity matches include glob pattern, and entity does not match any exclude criteria (domain, glob pattern or listed), accept + - If domain is not included, glob pattern does not match, and entity not included, reject + - Exclude domain and/or glob patterns specified and include does not list domains or glob patterns + - If domain is excluded and entity not included, reject + - If entity matches exclude glob pattern and entity not included, reject + - If entity does not match any exclude criteria (domain, glob pattern or listed), accept + - Neither include or exclude specifies domains or glob patterns + - If entity is included, accept (as #2 above) + - If entity include and exclude, the entity exclude is ignored + +The following characters can be used in entity globs: + +`*` - The asterisk represents zero, one, or multiple characters +`?` - The question mark represents a single character diff --git a/source/_integrations/alexa.smart_home.markdown b/source/_integrations/alexa.smart_home.markdown index 0edb9a933af..75d76ad3dfe 100644 --- a/source/_integrations/alexa.smart_home.markdown +++ b/source/_integrations/alexa.smart_home.markdown @@ -385,23 +385,7 @@ alexa: - light.kitchen_light ``` -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 +{% include common-tasks/filters.md %} 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 543d977c2f3..21b18a3837d 100644 --- a/source/_integrations/apache_kafka.markdown +++ b/source/_integrations/apache_kafka.markdown @@ -104,20 +104,4 @@ apache_kafka: - light.kitchen_light ``` -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 +{% include common-tasks/filters.md %} \ No newline at end of file diff --git a/source/_integrations/azure_event_hub.markdown b/source/_integrations/azure_event_hub.markdown index ee987ae9c06..f2355779316 100644 --- a/source/_integrations/azure_event_hub.markdown +++ b/source/_integrations/azure_event_hub.markdown @@ -57,23 +57,7 @@ azure_event_hub: - light.kitchen_light ``` -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 +{% include common-tasks/filters.md %} {% configuration %} filter: diff --git a/source/_integrations/google_pubsub.markdown b/source/_integrations/google_pubsub.markdown index f33c72b6d29..eb122bda972 100644 --- a/source/_integrations/google_pubsub.markdown +++ b/source/_integrations/google_pubsub.markdown @@ -104,23 +104,7 @@ google_pubsub: - light.kitchen_light ``` -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 +{% include common-tasks/filters.md %} ### Saving the data using a Google Cloud Function diff --git a/source/_integrations/history.markdown b/source/_integrations/history.markdown index a902b8e5621..39093a02cec 100644 --- a/source/_integrations/history.markdown +++ b/source/_integrations/history.markdown @@ -147,17 +147,7 @@ history: - light.front_porch ``` -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 specified entities and exclude specified entities from the remaining. - -The following characters can be used in entity globs: - -`*` - The asterisk represents zero, one, or multiple characters -`.` - The period represents a single character +{% include common-tasks/filters.md %} #### Implementation details diff --git a/source/_integrations/homekit.markdown b/source/_integrations/homekit.markdown index 69392fecd5d..5bff17a34ad 100644 --- a/source/_integrations/homekit.markdown +++ b/source/_integrations/homekit.markdown @@ -356,23 +356,7 @@ homekit: - light.kitchen_light ``` -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 +{% include common-tasks/filters.md %} Categorized entities are not included (config, diagnostic, and system entities) unless they are explicitly matched by `include_entity_globs` or `include_entities` or selected in the UI in include mode. diff --git a/source/_integrations/influxdb.markdown b/source/_integrations/influxdb.markdown index 3de3fb49b69..65c554f2ba5 100644 --- a/source/_integrations/influxdb.markdown +++ b/source/_integrations/influxdb.markdown @@ -229,23 +229,7 @@ influxdb: - light.kitchen_light ``` -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 +{% include common-tasks/filters.md %} ## Examples diff --git a/source/_integrations/logbook.markdown b/source/_integrations/logbook.markdown index 38794ba6b59..9f205556a78 100644 --- a/source/_integrations/logbook.markdown +++ b/source/_integrations/logbook.markdown @@ -83,17 +83,7 @@ logbook: - light.kitchen_light ``` -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 specified entities and exclude specified entities from the remaining. - -The following characters can be used in entity globs: - -- `*` - The asterisk represents zero, one, or multiple characters -- `.` - The period represents a single character +{% include common-tasks/filters.md %} ### Common filtering examples diff --git a/source/_integrations/mqtt_statestream.markdown b/source/_integrations/mqtt_statestream.markdown index 9a7fc966cae..d44cc95321d 100644 --- a/source/_integrations/mqtt_statestream.markdown +++ b/source/_integrations/mqtt_statestream.markdown @@ -93,23 +93,7 @@ mqtt_statestream: - light.kitchen_light ``` -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 +{% include common-tasks/filters.md %} ### Common filtering examples diff --git a/source/_integrations/prometheus.markdown b/source/_integrations/prometheus.markdown index 1c43dfc5d62..3e9a279a66e 100644 --- a/source/_integrations/prometheus.markdown +++ b/source/_integrations/prometheus.markdown @@ -112,23 +112,7 @@ prometheus: - light.kitchen_light ``` -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 +{% include common-tasks/filters.md %} ## Full Example diff --git a/source/_integrations/recorder.markdown b/source/_integrations/recorder.markdown index ba6ea0beef4..19809a497bf 100644 --- a/source/_integrations/recorder.markdown +++ b/source/_integrations/recorder.markdown @@ -137,23 +137,7 @@ recorder: - light.kitchen_light ``` -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 +{% include common-tasks/filters.md %} 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`). diff --git a/source/_integrations/splunk.markdown b/source/_integrations/splunk.markdown index d6d2db23f46..8943f48249c 100644 --- a/source/_integrations/splunk.markdown +++ b/source/_integrations/splunk.markdown @@ -102,20 +102,4 @@ splunk: - light.kitchen_light ``` -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 +{% include common-tasks/filters.md %} \ No newline at end of file diff --git a/source/_integrations/zabbix.markdown b/source/_integrations/zabbix.markdown index 925bde1f2ca..9c0ba343ec0 100644 --- a/source/_integrations/zabbix.markdown +++ b/source/_integrations/zabbix.markdown @@ -134,23 +134,7 @@ zabbix: {% 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 +{% include common-tasks/filters.md %} ## Sensor