home-assistant.io/source/_integrations/logbook.markdown

title, description, ha_category, ha_release, ha_domain

title	description	ha_category	ha_release	ha_domain
Logbook	Instructions on how to enable the logbook integration for Home Assistant.	History	0.7	logbook

The logbook integration provides a different perspective on the history of your house by showing all the changes that happened to your house in reverse chronological order. It depends on the recorder integration for storing the data. This means that if the recorder integration is set up to use e.g., MySQL or PostgreSQL as data store, the logbook integration does not use the default SQLite database to store data.

This integration is by default enabled, unless you've disabled or removed the default_config: line from your configuration. If that is the case, the following example shows you how to enable this integration manually:

# Example configuration.yaml entry
logbook:

{% configuration %} exclude: description: "Configure which integrations should not create logbook entries. (Configure Filter)" required: false type: map keys: entities: 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. (Configure Filter) required: false type: map keys: entities: 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 %}

# 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:

# Example of excluding domains and entities from the logbook
logbook:
  exclude:
    entities:
      - sensor.last_boot
      - sensor.date
    entity_globs:
      - sensor.weather_*
    domains:
      - sun

In case you just want to see messages from some specific entities or domains use the include configuration:

# Example to show how to include only the listed domains and entities in the logbook
logbook:
  include:
    domains:
      - sensor
      - switch
      - media_player

You can also use the include list and filter out some entities or domains with an exclude list. Usually this makes sense if you define domains on the include side and filter out some specific entities.

# Example of combining include and exclude configurations
logbook:
  include:
    domains:
      - sensor
      - switch
      - media_player
  exclude:
    entities:
      - sensor.last_boot
      - sensor.date
    entity_globs:
      - sensor.weather_*

Exclude Events

If you have sensor.date to show the current date in the UI, but you do not want a logbook entry for that sensor every day it can be excluded. To exclude these entities just add them to the exclude > entities list in the configuration of the logbook.

To exclude all events from a whole domain add it to the exclude > domain list. For instance you use the sun domain only to trigger automations on the azimuth attribute, then you possible are not interested in the logbook entries for sun rise and sun set.

Excluded entities still take up space in the database. It may be advisable to exclude them in recorder instead.

Custom Entries

It is possible to add custom entries to the logbook by using the script component to fire an event.

# Example configuration.yaml entry
script:
  add_logbook_entry:
    alias: Add Logbook
    sequence:
      - service: logbook.log
        data_template:
          name: Kitchen
          message: is being used
          # Optional
          entity_id: light.kitchen
          domain: light

When calling the logbook.log service without a domain or entity_id, entries will be added with the the logbook domain. Ensure that the logbook domain is not filtered away if you want these entries to appear in your logbook.

Sensor entities that have been assigned units (i.e., have a unit_of_measurement attribute) are assumed to change frequently and those sensors are automatically excluded from the logbook.