From 45b398c8a7f8297ada3ce82cd68e1dae7ede96d0 Mon Sep 17 00:00:00 2001 From: Max Rumpf Date: Sat, 7 Jan 2017 16:38:57 +0100 Subject: [PATCH] Add docs for include/exclude in recorder (#1714) Basically a copy of #1539, but with the changes requested (and some extra information copied from the history component). --- source/_components/recorder.markdown | 51 +++++++++++++++++++++++++++- 1 file changed, 50 insertions(+), 1 deletion(-) diff --git a/source/_components/recorder.markdown b/source/_components/recorder.markdown index f35cb8e8c5c..373b8144d0c 100644 --- a/source/_components/recorder.markdown +++ b/source/_components/recorder.markdown @@ -28,16 +28,65 @@ recorder: Configuration variables: - **purge_days** (*Optional*): Delete events and states older than x days. +- **exclude** (*Optional*): Configure which components should be excluded from recordings. + - **entities** (*Optional*): The list of entity ids to be excluded from recordings. + - **domains** (*Optional*): The list of domains to be excluded from recordings. +- **include** (*Optional*): Configure which components should be included in recordings. If set, all other entities will not be recorded. + - **entities** (*Optional*): The list of entity ids to be included from the history. + - **domains** (*Optional*): The list of domains to be included from the history. - **db_url** (*Optional*): The URL which point to your database. +Define domains and entities to `exclude` (aka. blacklist). This is convenient when you are basically happy with the information recorded, but just want to remove some entities or domains. Usually these are entities/domains which do not change (like `weblink`) or rarely change (`updater` or `automation`). + ```yaml -# Example configuration.yaml entry +# Example configuration.yaml entry with exclude recorder: purge_days: 5 db_url: sqlite:///home/user/.homeassistant/test + exclude: + domains: + - automation + - weblink + - updater + entities: + - sun.sun # Don't record sun data + - sensor.last_boot + - sensor.date ``` +Define domains and entities to record by using the `include` configuration (aka. whitelist). If you have a lot of entities in your system and your `exclude` lists possibly get very large, it might be better just to define the entities or domains to record. + +```yaml +# Example configuration.yaml entry with include +history: + include: + domains: + - sensor + - switch + - media_player +``` + +Use the `include` list to define the domains/entities to record, and exclude some of them with in the `exclude` list. This makes sense if you for instance include the `sensor` domain, but want to exclude some specific sensors. Instead of adding every sensor entity to the `include` `entities` list just include the `sensor` domain and exclude the sensor entities you are not interested in. + +```yaml +# Example configuration.yaml entry with include and exclude +history: + include: + domains: + - sensor + - switch + - media_player + exclude: + entities: + - sensor.last_boot + - sensor.date +``` + +If you only want to hide events from e.g. your history, take a look at the [`history` component](/components/history/). Same goes for logbook. But if you have privacy concerns about certain events or neither want them in history or logbook, you should use the `exclude`/`include` options of the `recorder` component, that they aren't even in your database. That way you can save storage and keep the database small by excluding certain often-logged events (like `sensor.last_boot`). + +## Custom database engines + | Database engine | `db_url` | | :---------------|:---------------------------------------------------------| | SQLite | `sqlite:///PATH/TO/DB_NAME` |