While developing the new version (2.3) of Consolation, I have encountered the following bugs in the documentation of the
log command in Sierra 10.12.5, and in its handling of predicates. If you use
log directly, you may wish to work around these.
man log contains a section headed
PREDICATE-BASED FILTERING EXAMPLES (the first of these, not the second which continues the title with
WITH LOG LINE).
The four examples given there will work, but the three which contain parentheses should be ignored, because of current problems in the parsing of predicates which contain parentheses (below).
Missing important information
The section headed
PREDICATE-BASED FILTERING fails to make a distinction between the keys
messageType, which are numeric, and other keys such as
eventMessage, which are strings.
The accepted key values, with their numeric equivalents, for
Note that you can pass either the names of the keys, which are case-sensitive, or numeric values, e.g.
messageType == info
messageType == 1
which are identical in meaning, or
eventType == activityCreateEvent
eventType == 513
which are identical in meaning.
Passing any of these using string syntax, such as
messageType == "info"
will not result in an error, but no log entries will be returned.
Other keys must be passed as strings, e.g.
eventMessage CONTAINS[c] "error"
The numeric keys can only meaningfully be used with numeric operators. Thus
messageType == info
returns all entries in which the log entry level is Info (note the difference in capitalisation, which is significant).
Using any string operator, such as
messageType CONTAINS[c] info
will not return an error, but will not return any results either.
However, you can use the equality operator (and others) on strings, such as
subsystem == "com.apple.TimeMachine"
which will return entries in which the specified subsystem ID is exactly that given.
Bug in parsing predicates
log show, and presumably
log stream, do not handle predicates containing parentheses consistently, and users are strongly advised to avoid the use of parentheses in predicates because of these inconsistencies.
Predicates which only use string-based keys appear to work fairly normally and correctly when parentheses are used, e.g.
'(subsystem == "com.apple.TimeMachine") && (eventMessage CONTAINS[c] "backup")'
However, any use of numeric-based keys with parentheses will not result in an error, but no log entries will be returned, e.g.
'(subsystem == "com.apple.TimeMachine") && (messageType == info)'
The only reliable workaround appears to be to express predicates wherever possible without the use of parentheses. For example, that last example works perfectly well when expressed as
'subsystem == "com.apple.TimeMachine" && messageType == info'
This is the approach which is now adopted by my Consolation app in version 2.3 in order to obtain more reliable and consistent log extracts.
I hope to submit these issues to Apple using its BugReporter.
I am very grateful to @JPoForenso who provided information on messageType and eventType which is reproduced above, and which gave me the clue to identify these problems.