illumos gate

fmdump is currently documented to AND together filters of distinct kinds; e.g., one may supply with -c and -n and only those records matching both will be in the output, and to OR together filters of the same kind; e.g., if one supplies multiple -n options, records matching either will be included.

This is mostly fine, but in some cases one is looking through a large number (thousands or more) of errors and would like to narrow the results much more deeply based on the properties of the events. For example, it may be desirable to include only those errors with a specified detector AND those with a particular PCIe UE status register value. Today there isn't really any way to do this without either (a) writing your own libexacct consumer -- because even the filtering code in libfmd_log can't do this -- or (b) using -V with grep -A/-B/-C on the result of a single filter, which works only if all the events happen to have the same number of properties in the same order. At best one can aggregate output by grepping and then doing | sort | uniq -c. All useful, but not nearly as useful as having an option to fmdump itself, built around an extension to libfmd_log's filtering capabilities, that acts as if each such filter were of a distinct kind, ANDing them together.

This leaves us with a couple of questions: first, what do we want to be able to do exactly? And second, the best way to implement this. The first observation is that the -n option and the logical behaviour of multiple filters of the same kind are documented. While the options are described by the manual as having an Evolving commitment level, this thing's been around a long time and we really should avoid breaking existing consumers. That means the semantics of existing commands with filters should be preserved. Next, we can notice that the idea of ANDing together other filter kinds doesn't make much sense: multiple -c options ANDed together could never match unless one was simply a subclass of another, -t and -T are already distinct from one another and any number of either ANDed together would always be equivalent to a single one of the same kind, and implicit filters like log_filter_silent are always collapsible.

What we'd really like to be able to do here is filter on (A and B) or (C and D and E) or F, where A through F are property presence/value matches. Of course it would also be possible to specify -c, the time options, and so on, and these would still be ANDed together as they are now.

The simpler, if less elegant and less useful, thing we could do is simply create a new kind of filter that behaves in the same way as -n but are always ANDed with one another as if they were each of a unique kind. This would enable filtering (A or B or C) and (D and E and F). That's still considerably more useful than what we have now, but less than ideal.

With all that in mind, what I think we want is an extension to the syntax for -n to accept a delimited list of name-value pairs, all of which must match. The remaining question is whether this can be implemented via the existing -n option or requires a new -N. It is possible for string/regex filters to contain whatever delimiter we might select (, is the obvious one, but ; would work too), so for compatibility purposes we probably need a new one. This also would be implemented in terms of a new filter function in libfmd_log, because the existing one is also exposed by the library, though it has no consumers other than fmdump and is seemingly Private (the FMD PRM specifies the log library interfaces as Contracted Consolidation Private).