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.