Lumberyard
User Guide (Version 1.21)

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 Macro Description
AZ_Assert

Use 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_Error

Use 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 (for example, in a message box or onscreen message).

AZ_Warning

Use 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_TracePrintf

Use for informational purposes only. AZ_TracePrintf macros print a message but take no other action.

For source code, see lumberyard_version\dev\Code\Framework\AzCore\AzCore\Debug\Trace.*.

Suppressing AZ Trace Messages in Unit Tests

You can use macros to suppress AZ trace messages. Starting in Lumberyard version 1.21, the following macros for suppressing AZ Trace messages in the AZ Unit Test framework have equivalent macros with new names. The old macros will be removed in a future release.

Old Macro Name New Macro Name
AZ_TEST_START_ASSERTTEST AZ_TEST_START_TRACE_SUPPRESSION
AZ_TEST_STOP_ASSERTTEST AZ_TEST_STOP_TRACE_SUPPRESSION

The old macros only suppressed the AZ_Error and AZ_Assert trace messages, but their names implied application termination. The new macros are equivalent in functionality to the old macros but have names that more accurately reflect their functionality.

For source code, see lumberyard_version\dev\Code\Framework\AzCore\AzCore\UnitTest\UnitTest.h.