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.

Other Logging Options

The streams array of the logging sections let you determine which streams receive log messages. By default, only the default section contains a streams section, so that all output from all subsystems is directed to one (or a small number of) log files.

There are two types of streams currently supported: console and file. The console stream logs to the system console (stdout), and may be specified only once. By default, the console stream will log only critical messages (level 0).

The file stream type logs to a file (no surprise). The name key sets the name of the file, and should be a simple filename only, not a pathname. The level key sets the minimum logging level required for a message to be output to the file (e.g. level 4 would direct information level and more severe, but no debug messages, which are levels 5+). The keep key tells the logger how many log rotations to keep, and the maxsize key sets the maximum size (in MB) to which a log file may grow before it is rotated. The mode key sets the file mode for new log files (using same numeric mode as chmod(1)). The file mode is subject to the process' umask, so specifying a mode of 0666 does not guarantee that the created file will get 0666 permissions — if the umask for the process is 022, then the log file will be created with 0644 (you'll have to change the process' umask if you want different behavior, which is OS-dependent and out of scope for this doc).

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