The static rules filter

You can use the static rules filter to track or filter events for many classes, certain events in a class, or even events related to specific process and thread IDs. You can select events in an additive or subtractive manner as explained below.

The static rules filter is the best, most efficient method of data reduction. It generally frees up the processor while significantly reducing the data rate. This filter is also useful for gathering large amounts of data periodically, or after many hours of logging without generating gigabytes of data in the interim.

You set up this filter using various TraceEvent() commands. For information about the different classes, see Classes and events in the Events and the Kernel chapter of this guide.

Here's a general outline for using the static rules filter:

1. Clear any existing filters. The instrumented kernel retains its settings, so you should be careful not to make any assumptions about the settings that are in effect when you set up your filters. Start by suppressing the tracing of all classes and events (except for Control events, which are always emitted):

   TraceEvent(_NTO_TRACE_DELALLCLASSES);

   The _NTO_TRACE_DELALLCLASSES command doesn't suppress any process- and thread-specific tracing that might have previously been set up. You need to clear it separately, by using the following TraceEvent() commands:

   To clear:	Call TraceEvent() with these arguments:
   Process-specific tracing of all events of a given class	_NTO_TRACE_CLRCLASSPID, class
   Process- and thread-specific tracing of all events of a given class	_NTO_TRACE_CLRCLASSTID, class
   Process-specific tracing of the given event in a given class	_NTO_TRACE_CLREVENTPID, class, event
   Process- and thread-specific tracing of a given event and class	_NTO_TRACE_CLREVENTTID, class, event

   For example, you might want to start by turning off all filtering:

   TraceEvent(_NTO_TRACE_DELALLCLASSES);
   TraceEvent(_NTO_TRACE_CLRCLASSPID, _NTO_TRACE_KERCALL);
   TraceEvent(_NTO_TRACE_CLRCLASSTID, _NTO_TRACE_KERCALL);
   TraceEvent(_NTO_TRACE_CLRCLASSPID, _NTO_TRACE_THREAD);
   TraceEvent(_NTO_TRACE_CLRCLASSTID, _NTO_TRACE_THREAD);
   TraceEvent(_NTO_TRACE_CLRCLASSPID, _NTO_TRACE_SYSTEM);
   TraceEvent(_NTO_TRACE_CLRCLASSTID, _NTO_TRACE_SYSTEM);
   TraceEvent(_NTO_TRACE_CLRCLASSPID, _NTO_TRACE_COMM);
   TraceEvent(_NTO_TRACE_CLRCLASSTID, _NTO_TRACE_COMM);
   

2. Set up the tracing of the event classes and types that you're interested in. You can do this in an additive or subtractive manner: you can start with no events and then add specific classes or events, or you can start with all events and then exclude specific ones.

   To:	Call TraceEvent() with these arguments:
   Enable the tracing of all standard classes and events (for a list of classes affected by this command, see the TraceEvent() entry)	_NTO_TRACE_ADDALLCLASSES
   Enable the tracing of all events in a specific class	_NTO_TRACE_ADDCLASS, class
   Enable the tracing of a specific event in a specific class	_NTO_TRACE_ADDEVENT, class, event
   Disable the tracing of all events in a specific class	_NTO_TRACE_DELCLASS, class
   Disable the tracing of a specific event in a specific class	_NTO_TRACE_DELEVENT, class, event

   Note:

   The event classes described in Classes and events and referred to throughout this guide are external classes, meaning their names are the ones used in the TraceEvent() commands. But the SAT uses its own internal classes when generating events and storing them in buffers. There is not a one-to-one mapping of external classes to internal classes; sometimes multiple external classes map to the same internal class. The mapping of external classes to internal classes is listed in the _NTO_TRACE_GET*(), _NTO_TRACE_SET*() entry in the C Library Reference.

3. Optionally restrict the tracing to a specific process or thread:

   To trace:	Call TraceEvent() with these arguments:
   All events for the given class for the given process	_NTO_TRACE_SETCLASSPID, class, pid
   All events for the given class for the given thread, specified by pid and tid	_NTO_TRACE_SETCLASSTID, class, pid, tid
   All events of the given type in the given class for the given process	_NTO_TRACE_SETEVENTPID, class, event, pid
   All events of the given type in the given class for the given thread, specified by pid and tid	_NTO_TRACE_SETEVENTTID, class, event, pid, tid

   You can set up class or event filtering for one process or thread at a time. That is, if you make a second TraceEvent() call with the same SETCLASS or SETEVENT control, then this changes the data generation source from the previously configured process or thread to the newly specified one—it does not enable event generation for both.

   For example, the following code sets up filtering for different classes for different processes:

   TraceEvent(_NTO_TRACE_SETCLASSPID, _NTO_TRACE_KERCALL, pid_1);
   TraceEvent(_NTO_TRACE_SETCLASSTID, _NTO_TRACE_THREAD, pid_2, tid_1);
   

   But the second call in this code overrides the setting made in the first call:

   TraceEvent(_NTO_TRACE_SETCLASSPID, _NTO_TRACE_KERCALL, pid_1);
   TraceEvent(_NTO_TRACE_SETCLASSTID, _NTO_TRACE_KERCALL, pid_2, tid_1);
   

For an example that uses the static filter, see the five_events.c example in the Tutorials chapter.