The static rules filter

You can use the static rules filter to track or filter events for all 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; 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.

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.

Note: You can set up process- and thread-specific tracing (using the _NTO_TRACE_SET* and _NTO_TRACE_CLR* commands described below) only for the following classes:

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 removing the tracing for all classes and events:
    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, int class
    Process- and thread-specific tracing of all events of a given class _NTO_TRACE_CLRCLASSTID, int class
    Process-specific tracing of the given event in a given class _NTO_TRACE_CLREVENTPID, int class, int event
    Process- and thread-specific tracing of a given event and class _NTO_TRACE_CLREVENTTID, int class, int 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_VTHREAD);
    TraceEvent(_NTO_TRACE_CLRCLASSTID, _NTO_TRACE_VTHREAD);
    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 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 classes and events _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
  3. Optionally restrict the tracing to a specific process, thread, or both:
    To trace: Call TraceEvent() with these arguments:
    All events for the given class that are for the process with the given ID _NTO_TRACE_SETCLASSPID, int class, pid_t pid
    All events for the given class that are for the process and thread with the given IDs _NTO_TRACE_SETCLASSTID, int class, pid_t pid, uint32_t tid
    All events of the given type in the given class that are for the process with the given ID _NTO_TRACE_SETEVENTPID, int class, int event, pid_t pid
    All events of the given type in the given class that are for the process and thread with the given IDs _NTO_TRACE_SETEVENTTID, int class, int event, pid_t pid, uint32_t tid

    You can set up class or event filtering for one process or thread at a time. For example, the following 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 the following 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.