Trace module

Summary: The Trace module provides performance tracking utility classes for counting, timing, measuring, recording, and reporting events.


Trace – Utilities for counting and recording events.

Classes:

AggregateNode

A representation of a call tree.

Collector

This is a singleton class that records TraceEvent instances and populates TraceCollection instances.

Reporter

This class converts streams of TraceEvent objects into call trees which can then be used as a data source to a GUI or written out to a file.

Functions:

TraceFunction(obj)

A decorator that enables tracing the function that it decorates.

TraceMethod(obj)

A convenience.

TraceScope(label)

A context manager that calls BeginEvent on the global collector on enter and EndEvent on exit.

class pxr.Trace.AggregateNode

A representation of a call tree. Each node represents one or more calls that occurred in the trace. Multiple calls to a child node are aggregated into one node.

Attributes:

children

list[AggregateNode]

count

int

exclusiveCount

int

exclusiveTime

TimeStamp

expanded

bool

expired

True if this object has expired, False otherwise.

id

Id

inclusiveTime

TimeStamp

key

str

property children

list[AggregateNode]

Type

type

property count

int

Returns the call count of this node.

recursive determines if recursive calls are counted.

Type

type

property exclusiveCount

int

Returns the exclusive count.

Type

type

property exclusiveTime

TimeStamp

Returns the time spent in this node but not its children.

Type

type

property expanded

bool

Returns whether this node is expanded in a gui.


type : None

Sets whether or not this node is expanded in a gui.

Type

type

property expired

True if this object has expired, False otherwise.

property id

Id

Returns the node’s id.

Type

type

property inclusiveTime

TimeStamp

Returns the total time of this node ands its children.

Type

type

property key

str

Returns the node’s key.

Type

type

class pxr.Trace.Collector

This is a singleton class that records TraceEvent instances and populates TraceCollection instances.

All public methods of TraceCollector are safe to call from any thread.

Methods:

BeginEvent(key)

Record a begin event with key if Category is enabled.

BeginEventAtTime(key, ms)

Record a begin event with key at a specified time if Category is enabled.

Clear()

Clear all pending events from the collector.

EndEvent(key)

Record an end event with key if Category is enabled.

EndEventAtTime(key, ms)

Record an end event with key at a specified time if Category is enabled.

GetLabel()

Return the label associated with this collector.

Attributes:

enabled

bool

expired

True if this object has expired, False otherwise.

pythonTracingEnabled

None

BeginEvent(key) TimeStamp

Record a begin event with key if Category is enabled.

A matching end event is expected some time in the future.

If the key is known at compile time BeginScope and Scope methods are preferred because they have lower overhead.

The TimeStamp of the TraceEvent or 0 if the collector is disabled.

BeginScope

Scope

Parameters

key (Key) –

BeginEventAtTime(key, ms) None

Record a begin event with key at a specified time if Category is enabled.

This version of the method allows the passing of a specific number of elapsed milliseconds, ms, to use for this event. This method is used for testing and debugging code.

Parameters
  • key (Key) –

  • ms (float) –

Clear() None

Clear all pending events from the collector.

No TraceCollection will be made for these events.

EndEvent(key) TimeStamp

Record an end event with key if Category is enabled.

A matching begin event must have preceded this end event.

If the key is known at compile time EndScope and Scope methods are preferred because they have lower overhead.

The TimeStamp of the TraceEvent or 0 if the collector is disabled.

EndScope

Scope

Parameters

key (Key) –

EndEventAtTime(key, ms) None

Record an end event with key at a specified time if Category is enabled.

This version of the method allows the passing of a specific number of elapsed milliseconds, ms, to use for this event. This method is used for testing and debugging code.

Parameters
  • key (Key) –

  • ms (float) –

GetLabel() str

Return the label associated with this collector.

property enabled

bool

Returns whether collection of events is enabled for DefaultCategory.


type : None

Enables or disables collection of events for DefaultCategory.

Type

classmethod type

property expired

True if this object has expired, False otherwise.

property pythonTracingEnabled

None

Set whether automatic tracing of all python scopes is enabled.


type : bool

Returns whether automatic tracing of all python scopes is enabled.

Type

type

class pxr.Trace.Reporter

This class converts streams of TraceEvent objects into call trees which can then be used as a data source to a GUI or written out to a file.

Methods:

ClearTree()

Clears event tree and counters.

GetLabel()

Return the label associated with this reporter.

Report(s, iterationCount)

Generates a report to the ostream s, dividing all times by iterationCount.

ReportChromeTracing(s)

Generates a timeline trace report suitable for viewing in Chrome's trace viewer.

ReportChromeTracingToFile

ReportTimes(s)

Generates a report of the times to the ostream s.

UpdateTraceTrees()

This fully re-builds the event and aggregate trees from whatever the current collection holds.

Attributes:

aggregateTreeRoot

AggregateNode

expired

True if this object has expired, False otherwise.

foldRecursiveCalls

bool

globalReporter

groupByFunction

bool

shouldAdjustForOverheadAndNoise

None

ClearTree() None

Clears event tree and counters.

GetLabel() str

Return the label associated with this reporter.

Report(s, iterationCount) None

Generates a report to the ostream s, dividing all times by iterationCount.

Parameters
  • s (ostream) –

  • iterationCount (int) –

ReportChromeTracing(s) None

Generates a timeline trace report suitable for viewing in Chrome’s trace viewer.

Parameters

s (ostream) –

ReportChromeTracingToFile()
ReportTimes(s) None

Generates a report of the times to the ostream s.

Parameters

s (ostream) –

UpdateTraceTrees() None

This fully re-builds the event and aggregate trees from whatever the current collection holds.

It is ok to call this multiple times in case the collection gets appended on inbetween.

If we want to have multiple reporters per collector, this will need to be changed so that all reporters reporting on a collector update their respective trees.

property aggregateTreeRoot

AggregateNode

Returns the root node of the aggregated call tree.

Type

type

property expired

True if this object has expired, False otherwise.

property foldRecursiveCalls

bool

Returns the current setting for recursion folding for stack trace event reporting.


type : None

When stack trace event reporting, this sets whether or not recursive calls are folded in the output.

Recursion folding is useful when the stacks contain deep recursive structures.

Type

type

globalReporter = <pxr.Trace.Reporter object>
property groupByFunction

bool

Returns the current group-by-function state.


type : None

This affects only stack trace event reporting.

If true then all events in a function are grouped together otherwise events are split out by address.

Type

type

property shouldAdjustForOverheadAndNoise

None

Set whether or not the reporter should adjust scope times for overhead and noise.

Type

type

pxr.Trace.TraceFunction(obj)

A decorator that enables tracing the function that it decorates. If you decorate with ‘TraceFunction’ the function will be traced in the global collector.

pxr.Trace.TraceMethod(obj)

A convenience. Same as TraceFunction but changes the recorded label to use the term ‘method’ rather than ‘function’.

pxr.Trace.TraceScope(label)

A context manager that calls BeginEvent on the global collector on enter and EndEvent on exit.