This documentation is for a prerelease version of O3DE. Click here to switch to the latest release, or select a version from the dropdown.

Version:

Debug Tracing

Recommended: For code tracing needs, use AZ_* tracing macros.

Reason: Error handling and tracing functions provide useful messages formatted for readability about errors that occur. To facilitate debugging, AZ_* tracing functions indicate where in code the errors occurred.

The following table describes the AZ_Tracing macros and their uses.


AZ Tracing MacroDescription
AZ_AssertUse for critical errors when the program cannot continue. AZ_Assert macros print an error message, the file name and line number where the error occurred, and then break program execution.
AZ_ErrorUse when an obvious error has occurred but the program can continue safely. AZ_Error macros print an error message and the file name and line number where the error occurred. In some environments, AZ_Error notifies the user that an error has occurred.
AZ_WarningUse when an error might have occurred. AZ_Warning macros print an error message and the file name and line number of the possible error, but take no other action.
AZ_InfoUse for informational purposes only. Info messages indicate that a normal, expected or relevant event has happened. AZ_Info macros print a message but take no other action.
AZ_TraceUse for debugging informational purposes only. AZ_Trace macros print a message but take no other action.
AZ_TracePrintf(Deprecated) Use for informational purposes only. AZ_TracePrintf macros print a message but take no other action. Prefer to use AZ_Info and AZ_Trace macros.

There are also versions of many of these macros that only get printed once, for example AZ_ErrorOnce. For source code, see Code\Framework\AzCore\AzCore\Debug\Trace.*.

Suppressing AZ Trace Messages in Unit Tests

You can use macros to suppress AZ trace messages.

  • AZ_TEST_START_ASSERTTEST - Enable AZ_Error and AZ_Assert trace messages
  • AZ_TEST_STOP_ASSERTTEST - Disable AZ_Error and AZ_Assert trace messages