jeans/home-assistant.io
jeans/home-assistant.io
1
0
Fork 0
mirror of https://github.com/home-assistant/home-assistant.io.git synced 2025-07-23 09:17:06 +00:00
Code Issues Packages Projects Releases Wiki Activity

Update doc for glob filter support (#13799)

Browse Source 
Co-authored-by: Franck Nijhof <git@frenck.dev>
This commit is contained in:
mdegat01 2020-06-24 08:25:22 -04:00 committed by GitHub
parent 1183534c52
commit 2c52fe6326
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
10 changed files with 519 additions and 95 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

49
source/_integrations/alexa.smart_home.markdown
View File

@ -228,6 +228,8 @@ alexa:
include_entities: include_entities:
- light.kitchen - light.kitchen
- light.kitchen_left - light.kitchen_left
include_entity_globs:
- binary_sensor.*_motion
include_domains: include_domains:
- switch - switch
exclude_entities: exclude_entities:
@ -273,7 +275,7 @@ alexa:
required: false required: false
type: string type: string
filter: filter:
description: Filter domains and entities for Alexa. description: Filter domains and entities for Alexa. ([Configure Filter](#configure-filter))
required: true required: true
type: map type: map
keys: keys:
@ -285,6 +287,14 @@ alexa:
description: List of domains to exclude (e.g., `light`). description: List of domains to exclude (e.g., `light`).
required: false required: false
type: list 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: include_entities:
description: List of entities to include (e.g., `light.attic`). description: List of entities to include (e.g., `light.attic`).
required: false required: false
@ -356,13 +366,15 @@ By default, no entity will be excluded. To limit which entities are being expose
```yaml ```yaml
# Example filter to include specified domains and exclude specified entities # Example filter to include specified domains and exclude specified entities
alexa: alexa:
smart_home: smart_home:
filter: filter:
include_domains: include_domains:
- alarm_control_panel - alarm_control_panel
- light - light
exclude_entities: include_entity_globs:
- light.kitchen_light - binary_sensor.*_occupancy
exclude_entities:
- light.kitchen_light
``` ```
{% endraw %} {% endraw %}
@ -373,16 +385,17 @@ Filters are applied as follows:
2. Includes, no excludes - only include specified entities 2. Includes, no excludes - only include specified entities
3. Excludes, no includes - only exclude specified entities 3. Excludes, no includes - only exclude specified entities
4. Both includes and excludes: 4. Both includes and excludes:
- Include domain specified - Include domain and/or glob patterns specified
- if domain is included, and entity not excluded, pass - If domain is included, and entity not excluded or match exclude glob pattern, pass
- if domain is not included, and entity not included, fail - If entity matches include glob pattern, and entity does not match any exclude criteria (domain, glob pattern or listed), pass
- Exclude domain specified - If domain is not included, glob pattern does not match, and entity not included, fail
- if domain is excluded, and entity not included, fail - Exclude domain and/or glob patterns specified and include does not list domains or glob patterns
- if domain is not excluded, and entity not excluded, pass - If domain is excluded and entity not included, fail
- if both include and exclude domains specified, the exclude domains are ignored - If entity matches exclude glob pattern and entity not included, fail
- Neither include or exclude domain specified - If entity does not match any exclude criteria (domain, glob pattern or listed), pass
- if entity is included, pass (as #2 above) - Neither include or exclude specifies domains or glob patterns
- if entity include and exclude, the entity exclude is ignored - 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. See the [troubleshooting](#troubleshooting) if for issues setting up the integration.

52
source/_integrations/apache_kafka.markdown
View File

@ -39,7 +39,7 @@ topic:
required: true required: true
type: string type: string
filter: filter:
description: Filters for entities to be included/excluded. description: Filters for entities to be included/excluded. ([Configure Filter](#configure-filter))
required: false required: false
type: map type: map
keys: keys:
@ -47,6 +47,10 @@ filter:
description: Domains to be included. description: Domains to be included.
required: false required: false
type: list type: list
include_entity_globs:
description: Include all entities matching a listed pattern.
required: false
type: list
include_entities: include_entities:
description: Entities to be included. description: Entities to be included.
required: false required: false
@ -55,8 +59,54 @@ filter:
description: Domains to be excluded. description: Domains to be excluded.
required: false required: false
type: list type: list
exclude_entity_globs:
description: Exclude all entities matching a listed pattern.
required: false
type: list
exclude_entities: exclude_entities:
description: Entities to be excluded. description: Entities to be excluded.
required: false required: false
type: list type: list
{% endconfiguration %} {% 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

57
source/_integrations/azure_event_hub.markdown
View File

@ -75,7 +75,7 @@ max_delay:
type: integer type: integer
default: 30 default: 30
filter: filter:
description: Filter domains and entities for Event Hub. description: Filter domains and entities for Event Hub. ([Configure Filter](#configure-filter))
required: true required: true
type: map type: map
default: Includes all entities from all domains default: Includes all entities from all domains
@ -88,6 +88,14 @@ filter:
description: List of domains to exclude (e.g., `light`). description: List of domains to exclude (e.g., `light`).
required: false required: false
type: list 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: include_entities:
description: List of entities to include (e.g., `light.attic`). description: List of entities to include (e.g., `light.attic`).
required: false required: false
@ -99,16 +107,59 @@ filter:
{% endconfiguration %} {% endconfiguration %}
<div class='note warning'> <div class='note warning'>
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.
</div> </div>
<div class='note warning'> <div class='note warning'>
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. 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.
</div> </div>
### 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 ### 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 ```yaml
# Connection string config with non-defaults for send_interval and max_delay # Connection string config with non-defaults for send_interval and max_delay

53
source/_integrations/google_pubsub.markdown
View File

@ -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) 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) 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 - Choose a new "New Service Account", give it a name and leave the key type as JSON
- Select the role: Pub/Sub Publisher - Select the role: Pub/Sub Publisher
@ -48,7 +49,7 @@ credentials_json:
required: true required: true
type: string type: string
filter: 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 required: true
type: map type: map
keys: keys:
@ -60,6 +61,14 @@ filter:
description: List of domains to exclude (e.g., `light`). description: List of domains to exclude (e.g., `light`).
required: false required: false
type: list 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: include_entities:
description: List of entities to include (e.g., `light.attic`). description: List of entities to include (e.g., `light.attic`).
required: false 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. 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.
</div> </div>
### 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 ### 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. 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.

33
source/_integrations/homekit.markdown
View File

@ -31,6 +31,8 @@ homekit:
- alarm_control_panel - alarm_control_panel
- light - light
- media_player - media_player
include_entity_globs:
- binary_sensor.*_occupancy
include_entities: include_entities:
- binary_sensor.living_room_motion - binary_sensor.living_room_motion
entity_config: entity_config:
@ -103,6 +105,10 @@ homekit:
description: Domains to be included. description: Domains to be included.
required: false required: false
type: list type: list
include_entity_globs:
description: Include all entities matching a listed pattern (e.g., `binary_sensor.*_motion`).
required: false
type: list
include_entities: include_entities:
description: Entities to be included. description: Entities to be included.
required: false required: false
@ -111,6 +117,10 @@ homekit:
description: Domains to be excluded. description: Domains to be excluded.
required: false required: false
type: list type: list
exclude_entity_globs:
description: Exclude all entities matching a listed pattern (e.g., `sensor.*_motion`).
required: false
type: list
exclude_entities: exclude_entities:
description: Entities to be excluded. description: Entities to be excluded.
required: false required: false
@ -371,6 +381,8 @@ homekit:
include_domains: include_domains:
- alarm_control_panel - alarm_control_panel
- light - light
include_entity_globs:
- binary_sensor.*_occupancy
exclude_entities: exclude_entities:
- light.kitchen_light - light.kitchen_light
``` ```
@ -383,16 +395,17 @@ Filters are applied as follows:
2. Includes, no excludes - only include specified entities 2. Includes, no excludes - only include specified entities
3. Excludes, no includes - only exclude specified entities 3. Excludes, no includes - only exclude specified entities
4. Both includes and excludes: 4. Both includes and excludes:
- Include domain specified - Include domain and/or glob patterns specified
- if domain is included, and entity not excluded, pass - If domain is included, and entity not excluded or match exclude glob pattern, pass
- if domain is not included, and entity not included, fail - If entity matches include glob pattern, and entity does not match any exclude criteria (domain, glob pattern or listed), pass
- Exclude domain specified - If domain is not included, glob pattern does not match, and entity not included, fail
- if domain is excluded, and entity not included, fail - Exclude domain and/or glob patterns specified and include does not list domains or glob patterns
- if domain is not excluded, and entity not excluded, pass - If domain is excluded and entity not included, fail
- if both include and exclude domains specified, the exclude domains are ignored - If entity matches exclude glob pattern and entity not included, fail
- Neither include or exclude domain specified - If entity does not match any exclude criteria (domain, glob pattern or listed), pass
- if entity is included, pass (as #2 above) - Neither include or exclude specifies domains or glob patterns
- if entity include and exclude, the entity exclude is ignored - If entity is included, pass (as #2 above)
- If entity include and exclude, the entity exclude is ignored
## Safe Mode ## Safe Mode

58
source/_integrations/logbook.markdown
View File

@ -26,7 +26,7 @@ logbook:
{% configuration %} {% configuration %}
exclude: 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 required: false
type: map type: map
keys: keys:
@ -34,12 +34,16 @@ exclude:
description: The list of entity ids to be excluded from creating logbook entries. description: The list of entity ids to be excluded from creating logbook entries.
required: false required: false
type: list 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: domains:
description: The list of domains to be excluded from creating logbook entries. description: The list of domains to be excluded from creating logbook entries.
required: false required: false
type: list type: list
include: include:
description: Configure which integrations should create logbook entries. description: Configure which integrations should create logbook entries. ([Configure Filter](#configure-filter))
required: false required: false
type: map type: map
keys: keys:
@ -47,12 +51,58 @@ include:
description: The list of entity ids to be included in creating logbook entries. description: The list of entity ids to be included in creating logbook entries.
required: false required: false
type: list 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: domains:
description: The list of domains to be included in creating logbook entries. description: The list of domains to be included in creating logbook entries.
required: false required: false
type: list type: list
{% endconfiguration %} {% 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 If you want to exclude messages of some entities or domains from the logbook
just add the `exclude` parameter like: just add the `exclude` parameter like:
@ -63,6 +113,8 @@ logbook:
entities: entities:
- sensor.last_boot - sensor.last_boot
- sensor.date - sensor.date
entity_globs:
- sensor.weather_*
domains: domains:
- sun - sun
``` ```
@ -96,6 +148,8 @@ logbook:
entities: entities:
- sensor.last_boot - sensor.last_boot
- sensor.date - sensor.date
entity_globs:
- sensor.weather_*
``` ```
### Exclude Events ### Exclude Events

145
source/_integrations/mqtt_statestream.markdown
View File

@ -38,7 +38,7 @@ publish_timestamps:
default: false default: false
type: boolean type: boolean
exclude: 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 required: false
type: list type: list
keys: keys:
@ -46,12 +46,16 @@ exclude:
description: The list of entity ids to be excluded from recordings. description: The list of entity ids to be excluded from recordings.
required: false required: false
type: list type: list
entity_globs:
description: Exclude all entities matching a listed pattern from recordings (e.g., `sensor.weather_*`).
required: false
type: list
domains: domains:
description: The list of domains to be excluded from recordings. description: The list of domains to be excluded from recordings.
required: false required: false
type: list type: list
include: 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 required: false
type: list type: list
keys: keys:
@ -59,12 +63,99 @@ include:
description: The list of entity ids to be included from recordings. description: The list of entity ids to be included from recordings.
required: false required: false
type: list type: list
entity_globs:
description: Include all entities matching a listed pattern in recordings (e.g., `sensor.weather_*`).
required: false
type: list
domains: domains:
description: The list of domains to be included from recordings. description: The list of domains to be included from recordings.
required: false required: false
type: list type: list
{% endconfiguration %} {% 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 ## Operation
When any Home Assistant entity changes, this integration will publish that change to MQTT. 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`. 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`. 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.

55
source/_integrations/prometheus.markdown
View File

@ -24,7 +24,7 @@ namespace:
required: false required: false
type: string type: string
filter: 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 required: false
type: list type: list
keys: keys:
@ -32,6 +32,10 @@ filter:
description: The list of entity ids to be excluded from recording. description: The list of entity ids to be excluded from recording.
required: false required: false
type: list type: list
exclude_entity_globs:
description: Exclude all entities matching a listed pattern (e.g., `sensor.weather_*`).
required: false
type: list
exclude_domains: exclude_domains:
description: The list of domains to be excluded from recording. description: The list of domains to be excluded from recording.
required: false 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. 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 required: false
type: list 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: 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. 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 required: false
type: list type: list
default_metric: default_metric:
type: string 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 required: false
default: uses the entity id of the entity default: uses the entity id of the entity
override_metric: override_metric:
@ -71,7 +79,7 @@ component_config_domain:
type: string type: string
description: Metric name to use instead of unit or default metric. This will store all data points in a single metric. description: Metric name to use instead of unit or default metric. This will store all data points in a single metric.
required: false required: false
component_config_glob: component_config_glob:
type: string type: string
required: false required: false
description: This attribute contains component-specific override values. See [Customizing devices and services](/getting-started/customizing-devices/) for format. 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 %} {% 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 ## Full Example
Advanced configuration example: Advanced configuration example:
@ -103,6 +150,8 @@ prometheus:
filter: filter:
include_domains: include_domains:
- sensor - sensor
exclude_entity_globs:
- sensor.weather_*
``` ```
You can then configure Prometheus to fetch metrics from Home Assistant by adding to its `scrape_configs` configuration. You can then configure Prometheus to fetch metrics from Home Assistant by adding to its `scrape_configs` configuration.

62
source/_integrations/recorder.markdown
View File

@ -63,7 +63,7 @@ recorder:
default: 1 default: 1
type: integer type: integer
exclude: 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 required: false
type: map type: map
keys: keys:
@ -71,6 +71,10 @@ recorder:
description: The list of domains to be excluded from recordings. description: The list of domains to be excluded from recordings.
required: false required: false
type: list type: list
entity_globs:
description: Exclude all entities matching a listed pattern from recordings (e.g., `sensor.weather_*`).
required: false
type: list
entities: entities:
description: The list of entity ids to be excluded from recordings. description: The list of entity ids to be excluded from recordings.
required: false required: false
@ -80,7 +84,7 @@ recorder:
required: false required: false
type: list type: list
include: 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 required: false
type: map type: map
keys: keys:
@ -88,12 +92,60 @@ recorder:
description: The list of domains to be included in the recordings. description: The list of domains to be included in the recordings.
required: false required: false
type: list type: list
entity_globs:
description: Include all entities matching a listed pattern from recordings (e.g., `sensor.weather_*`).
required: false
type: list
entities: entities:
description: The list of entity ids to be included in the recordings. description: The list of entity ids to be included in the recordings.
required: false required: false
type: list type: list
{% endconfiguration %} {% 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. 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 ```yaml
@ -105,6 +157,8 @@ recorder:
domains: domains:
- automation - automation
- updater - updater
entity_globs:
- sensor.weather_*
entities: entities:
- sun.sun # Don't record sun data - sun.sun # Don't record sun data
- sensor.last_boot # Comes from 'systemmonitor' sensor platform - sensor.last_boot # Comes from 'systemmonitor' sensor platform
@ -139,10 +193,10 @@ recorder:
entities: entities:
- sensor.last_boot - sensor.last_boot
- sensor.date - 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` ### 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. 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.

50
source/_integrations/splunk.markdown
View File

@ -50,7 +50,7 @@ name:
default: HASS default: HASS
type: string type: string
filter: 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 required: false
type: map type: map
keys: keys:
@ -58,6 +58,10 @@ filter:
description: Domains to be included. description: Domains to be included.
required: false required: false
type: list type: list
include_entity_globs:
description: Include all entities matching a listed pattern (e.g., `sensor.weather_*`).
required: false
type: list
include_entities: include_entities:
description: Entities to be included. description: Entities to be included.
required: false required: false
@ -66,8 +70,52 @@ filter:
description: Domains to be excluded. description: Domains to be excluded.
required: false required: false
type: list type: list
exclude_entity_globs:
description: Exclude all entities matching a listed pattern (e.g., `sensor.weather_*`).
required: false
type: list
exclude_entities: exclude_entities:
description: Entities to be excluded. description: Entities to be excluded.
required: false required: false
type: list type: list
{% endconfiguration %} {% 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