Filtering APIs

The filtering APIs include the following interfaces:

• bb_getfilters

• bb_getprodids

• bb_getseverity

• bb_setfilters

• bb_setprodids

• bb_setseverity

• BB_SEV_CLEAR

• BB_SEV_CLEAR_LIMIT

• BB_SEV_SET

• BB_SEV_SET_LIMIT

• BB_SEV_TEST

These interfaces enable three levels of pre-process event filtering; filter list, filtered severity bitmap, and global severity bitmap.

You can specify an event producer to use the filter list and filtered severity bitmap (also known as the fine grained filters) by identifying the producer in a set passed to bb_setprodids.

The filter list contains a set of pairs of tag and severity. These entities are described in the definition of bb_getseverity. An event is entered into the black box if:

• The call to bb_event has a tag that matches a tag in the filter list.

• The severity of the call is enabled in the tag's severity bitmap in the filter list.

• The caller of bb_event has been enabled to use the filter list.

The filter list can be updated by reading the current list with bb_getfilters, adding to it, subtracting from it, or modifying it, and then passing the new list to bb_setfilters.

The filtered severity bitmap is a node-wide severity bitmap. An event will be entered into the black box if:

• The call to bb_event has a severity that is enabled in the filtered severity bitmap.

• The caller of bb_event has been enabled to use the filtered severity bitmap.

The filtered severity bitmap can be updated by including a tag, severity filter with a tag of BB_ANY_TAG in a call to bb_setfilters.

The global severity bitmap is also a node-wide severity bitmap. If a call to bb_event does not find a match in the filter list or the filtered severity bitmap, or if the caller is not using these filters, the bb_event call will fall back to using the global severity bitmap. An event will be entered into the black box if the call to bb_event has a severity that is enabled in the global severity bitmap.

The global severity bitmap can be modified by calling bb_getseverity, modifying the bitmap, and passing the new bitmap to bb_setseverity.

The three filters are used in order, from the most to the least specific:

• filter list

• filtered severity bitmap

• global severity bitmap

If an event matches a filter in the filter list, it will added to the black box, otherwise it is tried against the filtered severity bitmap. If a match is found in the filtered severity bitmap, it will be added to the black box. If no match is found, it will be tried against the global severity bitmap. A consequence of this approach is that there is no strict filter out support. If the first filter tried does not match an event, another filter may find a match, even if the intent was for the more specific filter to filter it out. In such a case, however, the filters as specified are inconsistent, and a semantic should be chosen.