AAX SDK  2.4.1
Avid Audio Extensions Development Kit

How to add tracing to your plug-ins and view logging from the plug-in host.

On this page

What is DigiTrace?

DigiTrace is a logging tool used by many Avid audio applications. DigiTrace provides high-performance, real-time tracing capabilities and can help you debug hard-to-isolate problems in real-time code. Pro Tools and other Avid audio products are instrumented with DigiTrace, and it is easy to add DigiTrace logging to your AAX plug-ins.
This document outlines how to use DigiTrace, both as a developer to add trace instrumentation to your code and as an end user to view or record trace instrumentation for an instrumented application.

What does DigiTrace do?

DigiTrace generates encrypted logs on users' systems. These log files can be decrypted via the DigiTraceDecryptor application that is included in the DigiTrace Tools package.
By default, DigiTrace logs basic information including details about the system, software, component versions, and any errors that are encountered. By using a simple configuration text file, DigiTrace can be easily configured to provide additional logging information such as plug-in loading details. Here are some examples of how you can use DigiTrace:

DigiTrace quick start guide

This section provides quick steps for the following common tasks:

Find and decrypt DigiTrace log files

DigiTrace log files are placed into a common logs directory. The specific directory that is used depends on the version of DigiTrace - see Where are DigiTrace log files stored?
By default, the version of DigiTrace that is installed with Avid audio products generates logs in an encrypted format with the extension ".dlog". Developer builds of Pro Tools and other applications are configured to generate plain-text logs.
You can convert .dlog files to plain-text using the DigiTraceDecryptor tool that is included in the DigiTrace Tools package available for download from the Avid developer portal. To decrypt a log using this tool, simply drag-and-drop the .dlog file onto the tool. You can also set this tool as the default application for opening .dlog files in your OS, which will allow you to decrypt and open .dlog files directly.

Configure DigiTrace for AAX plug-in logging

You must customize the DigiTrace configuration to enable extra logging, such as debug logging for AAX plug-ins.
DigiTrace uses a plain-text configuration file to enable custom logging. This file uses the suffix ".digitrace" and is located within or beside the application. For example, the configuration files for Pro Tools are located at:
To configure DigiTrace to print logs from AAX_TRACE or AAX_TRACE_RELEASE macros in AAX plug-ins, add the following line to the .digitrace configuration file for the application:
DTF_AAXPLUGINS=file@DTP_LOWEST
If a config.digitrace file does not already exist for a DigiTrace-enabled application then you can create it to enable DigiTrace. For more information about customizing the DigiTrace configuration and enabling different levels of debug logging, see Configuring DigiTrace .

Configure DigiTrace for plain-text output

In order to be able to view streaming log output in real time, DigiTrace must be configured for plain-text output. This is the default configuration for developer builds of Pro Tools and other Avid audio applications.
To configure shipping applications for plain-text log output, you must replace the application's installed DigiTrace library with a development version of the DigiTrace library. Development builds of DigiTrace are included in the DigiTrace Tools package. Search for "Digitrace.framework" on macOS or "DigiTrace.dll" on Windows and replace the installed shipping version of the library with the developer version from the DigiTrace Tools package to configure the application for plain-text output.
Note that the developer version of DigiTrace may output logs to a different directory than the shipping version. In general, developer builds of DigiTrace will place log files in a directory next to the instrumented application. For example, developer builds of Pro Tools will output logs to a logs directory placed adjacent to the Pro Tools application bundle rather than in the user's Library/Logs/Avid folder.

Add tracing to a plug-in

To easily add tracing to an AAX plug-in, use the AAX_TRACE or AAX_TRACE_RELEASE macros. Logging from the "release" macro will be enabled for all builds of the plug-in, whereas logging from the "standard" macro will only be enabled in Debug builds of the plug-in.

DigiTrace log files

The default logging in Avid audio applications includes data that can be useful in many different troubleshooting situations. For example:
In addition, you can add DigiTrace logging code to your plug-ins, helping you examine potential issues in the way your plug-in is running on a user's computer even when you cannot reproduce the issue locally.

Where are DigiTrace log files stored?

Log directory

DigiTrace logs are stored in a log files directory on the user's system:
~/Library/Logs/Avid/ (macOS)
%userprofile%\AppData\Local\Avid\Logs or C:\Program Files\Avid\Pro Tools\Logs (Windows)
This default log directory can be overridden in the DigiTrace config file. See Advanced DigiTrace configuration for more information.

Log file names

By default the log file will be given a time-stamped name in the format <AppName>_YYYY_MM_DD_HH_MM_SS.dlog. This timestamp represents the system time when the log was created. Like the log directory, this log file name can be changed using the DigiTrace configuration. See Advanced DigiTrace configuration for more information.

Monitoring DigiTrace logs

Log files

You can of course view a log file by opening it periodically. In addition, assuming that DigiTrace is configured for plain text output, you can also constantly monitor a log file in a "streaming" manner. This is possible using standard Unix tools included with macOS or with Cygwin on Windows. In fact, this approach usually works better than telling DigiTrace to use console output due to buffering of the console output.

Console

Console behavior is quite different between macOS and Windows
Windows
On Windows, traces sent to the console go to the system debugging console. The only way to view the console output is to be running with an attached debugger.
macOS
On the Mac, console traces are sent to stdout console, which shows up in a few places:
  • If you're running in a debugger, the debug console will display stdout output, including DigiTrace messages
  • If you're not in the debugger, you can view the output in the Console app (/Applications/Utilities/Console). For Pro Tools, look under ~/Library/Logs/Avid/Pro Tools.X.log in the log list. Note that these messages are not displayed in the "All Messages" log.
  • Alternately, you can manually look at the log output, again using the tail command, e.g. tail -f "~/Library/Logs/Avid/Pro Tools.0.log"

Log file formatting

Here is the beginning of an example DigiTrace log:
*** Digidesign Session Trace for:	/Applications/Pro Tools 11.0.2 3PDev.app (pid=0x5aff, version=11.0.2d626)
*** Starting Timestamp:			Tuesday, January 7, 2014 4:10:57 PM Eastern Standard Time (89706938666 uS)
*** System Details:			OS Version: 10.8,5, CPU Speed:  2.7 gHz, Architecture: Intel 64 bit, Num Processors: 8 logical 4 physical, Memory: 16384 MB
*** DigiTrace Config File:		/Applications/Pro Tools 11.0.2 3PDev.app/Contents/Resources/config.digitrace
*** Facilities to trace:

DTF_INSTALLED_COMPONENTS@DTP_NORMAL(0e0d)

Time(us),Tid,Facility,Name : Debug Message
---------------------------------------------------------------------------
89707181683,00c07,0e0d: Pace eden lib version: 2.0.0, r22343 (2.0.0.22343),  [...]
89707220338,00c07,0e0d: ShoeTool_Init - shoe tool installed version is 6.000 [...]
89707220374,00c07,0e0d: ShoeTool_IncreaseAIOLimits - var=46, newVal=512, cur [...]
89707220380,00c07,0e0d: ShoeTool_IncreaseAIOLimits - var=47, newVal=512, cur [...]	 
The log file consists of a header followed by a series of log statements. Each log statement includes the following information:

Configuring DigiTrace

You can configure DigiTrace to include or exclude specific traces using the config.digitrace configuration file. This file is plain text and includes a single configuration command on each line.
This is the basic format for a command used to enable tracing for a single facility:
facility=[console@minimum console logging priority],[file@minimum file logging priority]
Here are some examples:
For more information about special configuration commands, see Advanced DigiTrace configuration.

Trace facilities

Trace facilities are used by DigiTrace to determine whether or not the given trace statement should be displayed. Trace facilities allow the user to filter trace statements at the component level.

Trace priorities

Trace priorities are used by DigiTrace to determine whether or not the given trace statement should be displayed. DigiTrace specifies five trace priorities:
The DigiTrace configuration file specifies minimum trace priorities. For example, if a trace statement uses DTP_LOW and DigiTrace is configured to use DTP_NORMAL as the minimum trace priority, then the trace statement will not be sent to the output target. In general, the DTP_LOWEST priority setting will populate the trace output with the most verbose information while the DTP_URGENT setting will output only the most high level details.

Useful DigiTrace facilities

This section includes descriptions of several facilities that are used in Pro Tools and other Avid audio products. The logging provided by these facilities may be helpful when diagnosing plug-in issues.

Bonus features

Real-time AAE performance logging with DigiTrace

Pro Tools 11 and higher includes logging for audio render callback performance. To enable this logging, enabled the DTF_DAE_HOSTDEVICE facility at DTP_URGENT. This facility will enable logging of real-time audio render thread metrics around any render errors that occur.
Here is an example of a performance log:
Int(LL): hstEr=0, ioEr=0, dif=2665(2891,23129), tot=2517(1648,2317), in=51(58,83), clbk=2158(1508,2158), out=108(99,164), offset=[12], mxW=1101(com.avid.aax.eleven.free)
The different values included in this log are:
A log of 'x=a (b,c)' means that the (x) value (e.g. tot) for the interrupt was (a) us, the running average was (b) us, and the maximum value encountered was (c) us. Therefore, in the example above:
In practice, it is difficult to precisely log this information during an error. This is due to changes in the interrupt pattern and scheduling when the audio engine is halted. In order to account for this, the performance logging will print out logs for several interrupts around when any error occurs. The actual audio engine error (hstEr) may be reported for a "junk" interrupt cycle that is spuriously logged during this halt process.

Adding signposts to the DigiTrace log at run-time

Use the shift-'~' key combination to add a "Trace Flag" line into the DigiTrace log. This allows you to add a "signpost" line to the log right when an important event happens, or before/after an important operation, so that it is easier to find the important details when inspecting the log later.
176603608088,2b603,0016: DSK_PrePrimeDiskTask::PrePrimeDiskTask - finish
176603961348,00307,0000: Trace Flag 3 (diff prev: 2.40s, diff start: 7.18s)
176605252296,00307,0000: Trace Flag 4 (diff prev: 1.29s, diff start: 8.47s)
176605252779,00307,0f09: 2016-07-19 23:36:32.499 PTC_Mgr::Idle() -- performing task (Websocket Base)
176606039830,00307,0000: Trace Flag 5 (diff prev: 0.79s, diff start: 9.26s)
Each trace flag signpost includes the text "Trace Flag" and the diff (in seconds) from both the previous trace flag and the first trace flag which was triggered during the current run of the app.
These lines will be printed regardless of the current DigiTrace configuration settings.
Host Compatibility Notes:
This feature is available in Pro Tools 12.6 and higher

Adding traces to an AAX plug-in

Basic AAX logging

Standard printf-style logging from AAX plug-ins is very easy. This feature is built into the AAX specification and is exposed to plug-ins via the AAX_TRACE and AAX_TRACE_RELEASE macros. For more information about basic logging, see the documentation for those macros.
Note
To enable basic AAX logging via these macros, the DTF_AAXPLUGINS trace facility must be enabled.

Tracing for AAX DSP

The AAX_TRACE and AAX_TRACE_RELEASE macros, as well as AAX_ASSERT, are cross-platform and are supported for use in AAX DSP algorithms. For more information about tracing from AAX DSP algorithms, see the Tracing section in the TI DSP Guide.

Advanced DigiTrace logging features

As a developer, you can use several advanced macros to extend the functionality of DigiTrace logging in your plug-in beyond the simple printf-style features provided by AAX_TRACE. The full DigiTrace macro suite includes macros for stack traces, very long traces, or even the ability to dump a block of memory to the log.
Note that these advanced features are only available on the host system. They are not currently available from algorithms running on embedded hardware.

What files do I include in my project?

To add advanced DigiTrace instrumentation to your source code you must:
  1. Include DigiTrace.h in the file where you are going to put your trace statements.
  2. Compile CDigitraceAccess.cpp into your project
If you have problems including the DigiTrace header file, try moving it to the top of the file that you're including it into. DigiTrace has no other dependencies and should be safe to include into any component.

What do I do if I encounter problems compiling or linking?

Should you run into linker errors or other problems after adding the DigiTrace header file, please go through the following items and verify that each is included in your project:

Macros

DigiTrace provides five core macros for trace output, which are:

Debug vs. release macros

All of the macros listed above are general-use macros, which generate output in both Debug and Release builds. They each have a debug-only variant which excludes the trailing "<TT>_R</TT>". Like AAX_TRACE, these debug-only versions compile to a noop in release builds.
The use of debug-only macros is not usually necessary due to the fact that release traces are encrypted and hidden from end users (but not from other developers.) As a best practice, we recommend using the "_R" version of a macro whenever possible. The debug versions of the macros should only be necessary in special circumstances where you specifically do not want to compile the code into release builds.
For more information about tracing in release builds see Security concerns

Syntax

Adding a DigiTrace statement to your code is as easy as making a single function call thanks to DigiTrace's predefined macros. The basic macro syntax is:
MACRO_NAME( TRACE_FACILITY_NAME [| TRACE_PRIORITY_LEVEL], MESSAGE_STRING )
Here is a code sample:
bool my_function(char* data_buffer, int data_buffer_len)
{
FXTRACE_R( DTF_PLUGINS_3P, "my_function" ); // Automatically trace function entry and exit.
// You need only to specify a trace facility.
OSErr err = FrobnicateBuffer(data_buffer, data_buffer_len);
if( noErr != err )
{
TRACE_R( DTF_PLUGINS_3P | DTP_HIGH, "Couldn't frobnicate the buffer: %s", OSErrToString(err) );
}
else
{
int cBytesToTrace = 64;
MEMTRACE( DTF_PLUGINS_3P | DTP_LOW, "Data after frobnication", data_buffer, cBytesToTrace );
}
}

Generating stack traces

The STACKTRACE_R macro is very useful for getting stack traces of important events in the code like throwing errors (which can be thrown from many locations). One particularly useful feature of this macro is that it allows you to specify a facility and priority for the printf part of the stacktrace, e.g. DTP_NORMAL, and another one for the stacktrace step, e.g. DTP_LOW. See DigiTrace.h for a full list of macros and their documentation.

Turning off tracing in a specific file

You can explicitly disable tracing in an instrumented file in the build by defining the MTurnDbgTraceOff symbol at the top of the file.

Security concerns

Unless you provide your own logging encryption, DigiTrace logs are not secure and should not be used to store any sensitive information.
Logs generated by Pro Tools release builds on users' systems are encrypted. This is primarily for the sake of avoiding confusion in our user community, since DigiTrace logs can be cryptic and potentially misleading for users who are not familiar with our code.
Avid and other third-party developers will see your plug-ins' release trace statements if they load your plug-ins with the appropriate trace facilities enabled. We highly recommend that you keep this in mind when developing your trace statements, both in order to prevent confusion (see the formatting guidelines in the AAX_TRACE_RELEASE documentation) and in order to maintain the security of your code.

Advanced DigiTrace configuration

The basic configuration command to enable tracing for a facility is described above in Configuring DigiTrace.
There are also additional commands that can be added to the DigiTrace configuration file for more advanced configurations.

Configuration command format

Advanced configuration commands

Dynamically changing the DigiTrace configuration

DigiTrace config files can be loaded dynamically, which means that you can add new configs while the instrumented application is running. Below are the details surrounding dynamic loading:

Compatibility

DigiTrace is an internal testing and troubleshooting tool. Although we will try to provide up-to-date documentation so that third-party developers can use this tool, we may need to change the way that DigiTrace works at some point and so we cannot make any promises regarding forwards-compatibility.
At the time of this writing:
If you notice significant bugs or other problems with DigiTrace in any Pro Tools release then we encourage you to report the issues to us on the developer forum. We may not be able to address issues immediately, but your feedback is appreciated.

Additional Information

Confidentiality

As with all information provided in the AAX SDK, the information provided in this documentation is confidential and is bound by the terms of your NDA with Avid. You may provide customized DigiTrace configuration files to end users in order to generate useful debugging information on their systems. However, you may not provide users with decrypted DigiTrace logs or with other details provided in this DigiTrace documentation.
Collaboration diagram for DigiTrace Guide: