Skip to content

Logging

Overview

When running, by default Reactor logs most messages to the reactor.log file in the Reactor installation directory, and to the console. The exact name of the log file and level of logging are determined by settings in config/logging.yaml.

The default log level sets the log level for all subsystems in Reactor when logging.yaml does not otherwise have a more specific rule. Do not change the default log level unless instructed to do so by the devs!

To help focus logging on specific subsystems or objects, the logging configuration allows you to add a subsystem/class name and a specific logging level. Here's an example logging.yaml file:

logging:
  default:
    level: 4
  # other data not shown for brevity

  Rule:
    level: 6
  Engine:
    level: 5
  VeraController:
    level: 4
  HassController#rpi:
    level: 7
  Entity#hass>switch_zooz_zen15_power_switch_switch
    level: 8

In the above example, the Engine and Rule subsystems are set to log at levels 5 and 6 respectively. The HomeAssistant controller instance (of class HassController) with ID "rpi" is set to level 7. The specific entity with ID hass>switch_zooz_zen15_power_switch_switch will log at level 8. The ability to set log levels with this kind of granularity is vital for producing usable logs during troubleshooting.

If you are asked to turn on logging for a particular subsystem as part of troubleshooting, just add the subsystem/class name given to the end of the list (unless it's already there — don't duplicate) indented two spaces and followed by a colon (:). Then, add another line after with level: indented four spaces (see the example above) and the numeric value for the level required. Don't forget to remove the entry or reduce the level when finished troubleshooting.

Attention

After modifying log levels, you must restart Reactor.

Logging and Entities

Turning up logging on a controller class to try to troubleshoot an entity or attribute problem is useful, but can also cause you to "sip from the firehose": it can dump a lot of information very quickly. If you are going to increase the log level on a Controller class, consider also temporarily configuring the controller to filter out entities that are not the focus of your troubleshooting, to reduce the volume of log data you need to look at.

Posting Log Snippets

If you are asked to post a log snippet, or you do so of your own initiative, please remember the following:

  • DO redact or mask passwords, API tokens, and other private data you would not want to see made public in your forum post, bug report, PasteBin, etc. If you want to privately email your log file, just PM toggledbits on the forums and I'll give you an address.
  • DO NOT redact the log data other than to remove or mask passwords, API tokens, and other private data as described above.
  • DO post at least twenty lines before and after the part you think is relevant. Most people have trouble identifying what is relevant in the logs (heck, most people don't even bother to look at them, sadly), and you'd be surprised how often people post one line from a log file, leaving out additional detail that explains the error or discloses data that could be used for diagnostics. Don't be "that guy." Context when posting log snippets is vital.
  • DO let us know what time zone you are in. While there are hourly messages logged that contain this information, if you're posting a snippet and not transferring the whole log, we won't see those, so we need to understand what your local time is relative to the UTC times in the log file.

Updated 2021-06-18