Logging

Power Manager maintains an audit log detailing the what, when, and why of the Scheduler's behaviour. The log provides an invaluable insight into how the Scheduler is performing.

Apple System Log

Power Manager uses Apple System Log (ASL). ASL is a standard part of macOS and any tool that supports ASL can be used to analyse Power Manager’s log entries. These tools include Console.app.

ASL extends syslog’s functionality and offers structured log entries. Structured log entries allow Power Manager to create log entries that contain tags specific to an event, trigger, condition, or action. Tools can filter log entries by unique IDs to quickly reveal information specific to an event, trigger, condition, or action.

Switching on Debug Logging

macOS does not record every log entry issued. Log entries have priorities, and only the higher priority entries are recorded. This is a deliberate design decision to help keep the logs free from debugging clutter and, normally, trivial content.

If you are experiencing problems, or want to know more about how Power Manager works, you should increase the range of priorities that are recorded to the the log. Typically, you will increase the range only for short periods of time: a day or two while you find and fix any problems.

Enabling all log entries

To increase the log priority range, you need to issue the commands below:

cd '/Applications/Power Manager.app/Contents/Tools'
./pmctl log.setfilterlevel "level=debug"

Restoring default log entries

To restore the log priority range to the default macOS settings, use the commands below:

cd '/Applications/Power Manager.app/Contents/Tools'
./pmctl log.setfilterlevel "level=notice"

For an explanation of how ASL’s filters work see macOS’s syslog manual page.

Unified Logging and `log`

macOS includes a logging approach called Unified Logging. This new system uses a database in place of the traditional text files. A query is required extract Power Manager related log entries from the database. The query is issued using macOS’s command line tool log.

Using `log` to view Power Manager log entries

log show --style syslog --info --debug --predicate 'senderImagePath ENDSWITH "pmd"'

For an explanation of how Unified Logging works see macOS’s log manual page.

Filter Levels

Power Manager can create log entries with differing levels of importance. The importance of a message determines if the message is stored to disk by Apple System Log (ASL).

Most log entries have an importance level denoting debug or informational content. By default messages of this level do not get stored and are discarded immediately. This filtering reduces clutter in the log files; only messages of note are stored.

The default log filter level is notice. This means log entries with importance levels below notice are not stored or displayed. Log entries with an importance tag of notice or higher, are stored and displayed in the log.

The importance levels are listed below in order of most important at the top, emergency, and least important at the bottom, debug.

emergency - most important
alert
critical
error
warning
notice
information
debug - least important

The log filter level can be adjusted.

Adjusting the Filter Level

Power Manager’s filter level can be adjusted using the log.setfilterlevel request.

Changes to the filter level affect all new log entries. Previous log entries are not affected. The existing log file remains unchanged by changes in the filter level.

To get and change the filter level, use the pmctl command line tool.

Use pmctl to get the filter level:

cd '/Applications/Power Manager.app/Contents/Tools'
./pmctl log.filterlevel "notice"

Use pmctl to adjust the filter level:

cd '/Applications/Power Manager.app/Contents/Tools'
./pmctl log.setfilterlevel level=debug

Structured Log Entries

Power Manager takes full advantage of ASL’s structured log entries. Unlike the legacy syslog method of logging, ASL allows log entries to include structured information. This information is stored in the form of a key and value pair; much like a dictionary.

All Power Manager log entry keys share the common prefix of uk.co.dssw.powermanager. This prefix is reserved by DssW for exclusive use by Power Manager.

Power Manager log entries may include any combination of the following keys.

relationship.primary
relationship.secondary: Item the message relates to. Use the value to fetch the unique ID of the referred item.

A message may refer to two items. A message referring to the performing of an event’s actions might include uk.co.dssw.powermanager.event as the primary relationship, and uk.co.dssw.powermanager.action as the secondary relationship.

event
trigger
condition
action: Unique ID of the item being referred to.
iopmqueue: Unique ID of the IOPMQueue hardware event being referred to.