Diagnostic Messages (Logs)#

Specialized handling of OpenUSD TfDiagnostic messages (logs).

The Tf module from OpenUSD provides various diagnostic logging abilities, including the ability to override the default message handler (which prints to stderr) with one or more custom handlers.

These functions can be used to control a specialized TfDiagnosticMgr::Delegate provided by OpenUSD Exchange. The primary advantages of this Delegate are:

Diagnostics can be filtered by DiagnosticsLevel.
Diagnostics can be redirected to stdout, stderr, or muted entirely using DiagnosticsOutputStream.
The message formatting is friendlier to end-users.

Note

Use of this Delegate is entirely optional and it is not activated by default when loading this module. To active it, client code must explicitly call activateDiagnosticsDelegate(). This is to allow clients to opt-in and to prevent double printing for clients that already have their own TfDiagnosticMgr::Delegate implementation.

Enumerations#

usdex::core::DiagnosticsLevel: Controls the diagnostics that will be emitted when the Delegate is active.
usdex::core::DiagnosticsOutputStream: Control the output stream to which diagnostics are logged.

Functions#

void usdex::core::activateDiagnosticsDelegate(): Activates the Delegate to specialize TfDiagnostics handling.
void usdex::core::deactivateDiagnosticsDelegate(): Deactivates the Delegate to restore default TfDiagnostics handling.
DiagnosticsLevel usdex::core::getDiagnosticsLevel(): Get the current DiagnosticsLevel for the Delegate .
DiagnosticsOutputStream usdex::core::getDiagnosticsOutputStream(): Get the current DiagnosticsOutputStream for the Delegate .
bool usdex::core::isDiagnosticsDelegateActive(): Test whether the Delegate is currently active.
void usdex::core::setDiagnosticsLevel(DiagnosticsLevel value): Set the DiagnosticsLevel for the Delegate to filter TfDiagnostics by severity.
void usdex::core::setDiagnosticsOutputStream(DiagnosticsOutputStream value): Set the DiagnosticsOutputStream for the Delegate to redirect TfDiagnostics to different streams.

Enumerations#

enum class usdex::core::DiagnosticsLevel#

Controls the diagnostics that will be emitted when the Delegate is active.

Values:

enumerator eFatal#: Only TF_FATAL are emitted.

enumerator eError#: Emit TF_ERROR and TF_FATAL, but suppress TF_WARN and TF_STATUS diagnostics.

enumerator eWarning#: Emit TF_WARN, TF_ERROR, and TF_FATAL, but suppress TF_STATUS diagnostics.

enumerator eStatus#: All diagnostics are emitted.

enum class usdex::core::DiagnosticsOutputStream#

Control the output stream to which diagnostics are logged.

Values:

enumerator eNone#: All diagnostics are suppressed.

enumerator eStdout#: All diagnostics print to the stdout stream.

enumerator eStderr#: All diagnostics print to the stderr stream.

Functions#

void usdex::core::activateDiagnosticsDelegate()#

Activates the Delegate to specialize TfDiagnostics handling.

When active, the Delegate replaces the default TfDiagnosticMgr printing with a more customized result. See Diagnostic Messages (Logs) for more details.

Note

The delegate is not active when this module loads. Clients must explicitly call this function to activate it.

void usdex::core::deactivateDiagnosticsDelegate()#

Deactivates the Delegate to restore default TfDiagnostics handling.

When deactivated, the default TfDiagnosticMgr printing is restored, unless some other Delegate is still active. See Diagnostic Messages (Logs) for more details.

DiagnosticsLevel usdex::core::getDiagnosticsLevel()#

Get the current DiagnosticsLevel for the Delegate.

This can be called at any time, but the filtering will only take affect after calling activateDiagnosticsDelegate(). See Diagnostic Messages (Logs) for more details.

Returns:: The current DiagnosticsLevel for the Delegate.

DiagnosticsOutputStream usdex::core::getDiagnosticsOutputStream()#

Get the current DiagnosticsOutputStream for the Delegate.

This can be called at any time, but will only take affect after calling activateDiagnosticsDelegate(). See Diagnostic Messages (Logs) for more details.

Returns:: The current DiagnosticsOutputStream for the Delegate.

bool usdex::core::isDiagnosticsDelegateActive()#

Test whether the Delegate is currently active.

When active, the Delegate replaces the default TfDiagnosticMgr printing with a more customized result. See Diagnostic Messages (Logs) for more details.

Returns:: Whether the Delegate is active

void usdex::core::setDiagnosticsLevel(DiagnosticsLevel value)#

Set the DiagnosticsLevel for the Delegate to filter TfDiagnostics by severity.

This can be called at any time, but the filtering will only take affect after calling activateDiagnosticsDelegate(). See Diagnostic Messages (Logs) for more details.

Parameters:: value – The highest severity DiagnosticsLevel that should be emitted.

void usdex::core::setDiagnosticsOutputStream( DiagnosticsOutputStream value, )#

Set the DiagnosticsOutputStream for the Delegate to redirect TfDiagnostics to different streams.

This can be called at any time, but will only take affect after calling activateDiagnosticsDelegate(). See Diagnostic Messages (Logs) for more details.

Parameters:: value – The stream to which all diagnostics should be emitted.