Managing Power Manager
Logging
Power Manager maintains an audit log detailing the what, when, and why of the engine’s behaviour. The log provides an invaluable insight into how the engine 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. Power Manager’s log entries are included in the system.log and console.log files. Power Manager’s log can be integrated into environments using remote syslog configurations.
ASL 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.
To increase the log priority range, you need to issue the commands in Example 1.1, “Enabling all log entries”.
Example 1.1. Enabling all log entries
cd '/Applications/Power Manager.app/Contents/Tools'
./pmctl log.setfilterlevel "level=debug"
sudo syslog -c syslogd -d
sudo syslog -c pmd -d
To restore the log priority range to the default macOS settings, use the commands in Example 1.2, “Restoring default log entries”
Example 1.2. Restoring default log entries
cd '/Applications/Power Manager.app/Contents/Tools'
./pmctl log.setfilterlevel "level=notice"
sudo syslog -c syslogd -n
For an explanation of how ASL’s filters work see macOS’s syslog(1) manual page.
Unified Logging and log
In macOS 10.12, Apple introduced a new 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.
Example 1.3. 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(1) manual page.
Using Console
On macOS 10.11 and earlier, Apple’s Console.app application includes useful filtering tools. You can use these tools to view only Power Manager related log entries.
The following steps show how to create a filter that displays only Power Manager log entries.
Procedure 1.1. Displaying Power Manager Entries
Launch Console.
Applications/Utilities/Console.appCreate a new log database query.
File > New Log Database Query… (macOS 10.5)
File > New Database Search… (macOS 10.6)
Filter the messages by Facility. All Power Manager messages have a facility tag starting with
uk.co.dssw.powermanager.
Complete the query panel so that it matches the settings from the following table.
Table 1.1. Filter Messages By Facility
Tag Operator Value Facility starts with uk.co.dssw.powermanagerClick OK to create the new query.
The new query will appear in the Log List panel. Click on the query to show only Power Manager log entries.
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 importantalertcriticalerrorwarningnoticeinformationdebug- 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.
Example 1.4. Using pmctl to get the filter level
cd '/Applications/Power Manager.app/Contents/Tools'
./pmctl log.filterlevel "notice"
Example 1.5. Using 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.eventas the primary relationship, anduk.co.dssw.powermanager.actionas 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.