|
The trace library consists of two main components:
The TraceCollector class can be used as a recorder for custom events in an application without using TRACE_ macros.
Most of the time TRACE macros are sufficient for instrumentation, however if something more specific is required, the TraceCollector class can be used directly without using TRACE_ macros. The macros simply invoke API on the TraceCollector.
Each TraceEvent contains a TraceCategoryId. These ids allow for the events to be filtered. Events recorded by TRACE_ macros have their TraceCategoryId set to TraceCategory::Default.
Trace categories consist of two parts, a TraceCategoryId, and a function to determine whether or not events for the category should be recorded.
TraceCategory::CreateTraceCategoryId can create a TraceCategoryId from hashing a string literal. This is not guaranteed to be unique.
All of the methods in the TraceCollector class which record events take an optional Category template parameter. The Category template parameter determines if the event will be recorded and the TraceCategoryId that will be stored in the event.
A valid Category template parameter must have have the following:
If the Category template parameter is not specified, TraceCollector uses TraceCollector::DefaultCategory.
Example of recording an event with a custom category.
Access to recorded TraceEvent objects is available through the TraceCollection class and TraceCollectionAvailable notice. When the TraceCollector produces data through the TraceCollector::CreateCollection() method, it will send a TraceCollectionAvailable notice. To access individual events in a TraceCollection instance, the TraceCollection::Visitor interface can be used. The TraceReporterBase class encapsulates logic for handling TraceCollectionAvailable notices.
Example of using TraceReporterBase class and TraceCollection::Visitor interface.