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.

Misleading examples

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 eventType and messageType, which are numeric, and other keys such as eventMessage, which are strings.

The accepted key values, with their numeric equivalents, for eventType are:

• activityCreateEvent (513)
• activityTransitionEvent (514)
• traceEvent (768)
• logEvent (1024)

Those for messageType are:

• default (0)
• release (0)
• info (1)
• debug (2)
• error (16)
• fault (17)

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.