Defines utility classes for counting, timing, measuring, and recording events. The TraceCollector class records TraceEvent objects. The TraceReporter class contains functions to generate reports on events gathered by the TraceCollector object.
Instrumentation
Instrumentation is done by adding TRACE macros to code.
Adding Trace macros does have a small overhead even when tracing is disabled. Sometimes a performance sensitive function may have a slow path that is taken infrequently, but timing information is needed. In cases like this, it is possible to reduce the overhead of the instrumentation to specific scopes.
// This is an example of a performance sensitive function that has a slow path.
void PerformanceSensitiveFunction(bool slowPath)
{
// No TRACE Macro is used in the fast path to avoid any overhead.
if (slowPath) {
// This will only pay the overhead cost of the trace instrumentation on
Recording is done through the TraceCollector class. Enabling the collector will cause TRACE macros to record events. Reports are generated with the TraceReporter class.
A report can also be generated from a program instrumented with libtrace using the PXR_ENABLE_GLOBAL_TRACE environment variable. If this variable is set, the TraceCollector singleton will start recording on initialization, and a report will be written to stdout at program exit.
The dynamic versions of the macros TRACE_FUNCTION_DYNAMIC(), TRACE_SCOPE_DYNAMIC() have a much higher overhead than the static versions. The reason for this is that for the static versions, the names of the scopes are compiled as constexpr data, but the dynamic versions construct strings at runtime. This overhead of dynamic macros is true whether tracing is enabled or not. Because of this, the static versions should be preferred whenever possible.
It is possible to disable TRACE macros from generating code by defining TRACE_DISABLE in the preprocessor.
The TraceCollector class and TRACE macros are thread-safe.