Chapter 1. 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 Mac OS X 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

Mac OS X 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

bash% cd '/Applications/Power Manager.app/Contents/Tools'
bash% ./pmctl log.setfilterlevel "level=debug"
bash% sudo syslog -c syslogd -d
bash% sudo syslog -c pmd -d


To restore the log priority range to the default Mac OS X settings, use the commands in Example 1.2, “Restoring default log entries”.

Example 1.2. Restoring default log entries

bash% cd '/Applications/Power Manager.app/Contents/Tools'
bash% ./pmctl log.setfilterlevel "level=notice"
bash% sudo syslog -c syslogd -n


For an explanation of how ASL's filters work see Mac OS X's syslog(1) manual page.

Using Console

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

  1. Launch Console.

    Applications/Utilities/Console.app

  2. Create a new log database query.

    File > New Log Database Query… (Mac OS X 10.5)

    File > New Database Search… (Mac OS X 10.6)

  3. 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.powermanager

  4. Click OK to create the new query.

  5. 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 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.

Example 1.3. Using pmctl to get the filter level

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


Example 1.4. Using pmctl to adjust the filter level

bash% cd '/Applications/Power Manager.app/Contents/Tools'
bash% ./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.