The trace library consists of two main components:
- TraceCollector is a singleton thread-safe recorder of events.
- TraceReporter is a class which processes events to create meaningful views of the data.
The TraceCollector class can be used as a recorder for custom events in an application without using TRACE_ macros.
Contents
Recording Events with TraceCollector
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:
- A thread-safe static method named GetId which returns a TraceCategoryId.
- A thread-safe static method named IsEnabled which returns a bool.
If the Category template parameter is not specified, TraceCollector uses TraceCollector::DefaultCategory.
Example of recording an event with a custom category.
struct CustomPerfCounterCategory
{
}
static bool IsEnabled();
};
int main(int argc, char *argv[])
{
}
Accessing Trace Data
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.
class CustomTraceEventProcessor :
public:
CustomTraceEventProcessor();
virtual void OnEndThread(
const TraceThreadId&)
override;
void Update() {
}
protected:
collection->Iterate(*this);
}
};
Example of Custom Category and Reporter
#include "pxr/base/trace/collector.h"
#include "pxr/base/trace/reporterBase.h"
#include <atomic>
#include <map>
PXR_NAMESPACE_USING_DIRECTIVE
struct CustomPerfCounterCategory
{
}
static bool IsEnabled() {
return _isEnabled.load(std::memory_order_acquire);
}
static void Enable() {
_isEnabled.store(true, std::memory_order_release);
}
static void Disable() {
_isEnabled.store(false, std::memory_order_release);
}
private:
static std::atomic<bool> _isEnabled;
};
#define CUSTOM_PERF_COUNTER(name, value) \
_CUSTOM_PERF_COUNTER_INSTANCE(__LINE__, name, value)
#define _CUSTOM_PERF_COUNTER_INSTANCE(inst, name, value) \
static constexpr TraceStaticKeyData customCounterKey ## inst (name); \
TraceCollector::GetInstance().RecordCounterDelta<CustomPerfCounterCategory>(customCounterKey ## inst, value);
class CustomTraceEventProcessor :
public:
CustomTraceEventProcessor(TraceReporterDataSourceBaseRefPtr dataSource)
{}
void Update() {
}
return id == CustomPerfCounterCategory::GetId();
}
}
}
virtual void OnEndThread(
const TraceThreadId&)
override {}
protected:
collection->Iterate(*this);
}
std::map<TfToken, double> _counters;
};
void Foo()
{
CUSTOM_PERF_COUNTER("Foo Counter",1);
}
std::atomic<bool> CustomPerfCounterCategory::_isEnabled(false);
int main(int argc, char *argv[])
{
CustomPerfCounterCategory::GetId(), "CustomPerfCounter");
CustomTraceEventProcessor eventProcessor(
CustomPerfCounterCategory::Enable();
Foo();
CustomPerfCounterCategory::Disable();
eventProcessor.Update();
}