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:
-
You can use DigiTrace in your plug-ins when you need a convenient, high-performance logging solution.
-
You can use the default DigiTrace logs that Pro Tools generates to help you understand problems that your plug-ins encounter when running on Pro Tools.
-
You can add DigiTrace statements and stack traces to your released plug-ins in order to help you troubleshoot end-user issues more quickly.
-
You can (and should!) submit DigiTrace logs when reporting bugs and other Pro Tools issues to Avid.
DigiTrace quick start guide
This section provides quick steps for the following common tasks:
Find and decrypt DigiTrace log files
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:
- macOS: Pro Tools.app/Contents/Resources/config.digitrace
- Windows: C:\Program Files\Avid\Pro Tools\ProTools.digitrace
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:
- Information about the user's system configuration
- A complete list of loaded components and libraries. (If the user has an old or incompatible version of your plug-ins installed on his system, you will know about it!)
- Crash logs in the event of a system failure
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)
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:
-
Time(us) - The time the message was logged, in microseconds since the machine was started.
-
Tid - The thread ID of the thread that logged the message.
-
Facility - The Facility ID of the facility that's logging the message.
-
Name - This is the config name added to all facilites included by this config file. This can be used to group all facilites related to a feature set, for instance. If not set, this is not included.
-
Debug Message - This is the actual string passed to the trace facility.
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:
-
DTF_APP_VERSION=file@DTP_LOW
-
DTF_PLUGINS_3P=file@DTP_LOW,console@DTP_URGENT
-
DTF_ASSERTHANDLER=console@DTP_URGENT
-
DTF_DAE_MEM=console@DTP_URGENT,file@DTP_LOWEST
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:
-
DTP_LOWEST
-
DTP_LOW
-
DTP_NORMAL
-
DTP_HIGH
-
DTP_URGENT
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.
-
DTF_AAXPLUGINS
This is the standard facility for
AAX plug-ins. This facility will only log traces that are present in
AAX plug-ins themselves, not traces in any hosting code. Plug-ins may use the
AAX_TRACE or
AAX_TRACE_RELEASE macros to log to this facility.
- Note
- Disabling the
DTF_AAXPLUGINS
facility will slightly reduce the overhead of trace statements and chip communication on HDX systems.
-
DTF_AAXHOST
at DTP_NORMAL
Logging from the main
AAX host component. Use a lower priority for additional
AAX Host tracing.
-
DTF_PLUGINS
at DTP_LOW
Miscellaneous plug-in operations, including page table logging, preset directory errors, and DLL loading and unloading
-
DTF_TIPLUGINS
at DTP_NORMAL
Logging for HDX plug-in algorithm handling details such as packet management and private data field state reset. Use DTP_LOW
for deeper tracing.
-
DTF_TISHELLMGR
at DTP_HIGH
Logging from the HDX RTOS
-
DTF_DAE_HOSTDEVICE
at DTP_URGENT
Performance logging from the real-time audio render thread. See
Real-time AAE performance logging with DigiTrace
-
DTF_DAE_ERRORS
at DTP_NORMAL
or DTP_LOW
Information about any errors that occur in AAE. Use DTP_LOW
to enable stack traces.
-
DTF_ASSERTHANDLER
at DTP_NORMAL
or DTP_LOW
Similar to DTF_DAE_ERRORS
: Information about any asserts that fail. Use DTP_LOW
to enable stack traces.
-
DTF_THREAD_NAMES_AND_PRIORITIES
at DTP_NORMAL
or DTP_LOW
Allows you to look up a thread's debug name from its ID on the standard trace line. Thread names and IDs will be traced as they are created, and you can then use that ID to resolve the thread name of later trace statements. Use DTP_NORMAL
for just names and IDs, and DTP_LOW
to include priorities.
-
DTF_PACESUPPORT
at DTP_NORMAL
Plug-in digital signature logging, with some diagnostics for digital signature verification failures.
-
DTF_ADC
at DTP_NORMAL
Delay compensation logging, including host accounting for plug-in latency.
-
DTF_AUTOMATION
at DTP_LOW
Parameter touch and release logging.
-
DTF_AUDIOSUITE
at
Logging of events specific to AudioSuite plug-in instances.
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:
-
hstEr
-
ioEr
-
dif
-
tot
-
in
-
clbk
-
out
-
offset
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:
-
1648 us average total time was spent in each interrupt
-
2517 us was spent in this interrupt
-
Eleven Free was the longest worker in this interrupt
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.
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
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:
- Include DigiTrace.h in the file where you are going to put your trace statements.
- 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:
- The CDigitraceAccess.cpp file automatically searches for and loads the DigiTrace.dll (Windows) or DigiTrace.framework (Mac) component and ensures that the appropriate function pointers are initialized. If you receive linker errors, the missing symbols are likely in this file. Note that your project will need the path to CDigiTraceAccess.h in order to compile this file.
- If you receive an include file error for DigiPragmas.h then you will need to add the header's path to your project's search paths. This file is included in the most recent DigiTrace Tools packages but may not be included in some older packages.
Macros
DigiTrace provides five core macros for trace output, which are:
TRACE_R
- for general printf style tracing. Subject to a total line limit of 256 chars.
TRACE_PUTS_R
- prints an arbitrary length buffer, splitting it up into clean lines based on line breaks. No formatting.
STACKTRACE_R
- for stack trace printing. See below.
MEMTRACE_R
- for memory buffer hex tracing
FXTRACE_R
- for automatic function entry and exit tracing
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.
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" );
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
-
All DigiTrace configuration commands are listed in the configuration file with the form <token>=<value>
-
Any blank line or line beginning with a '
#
' character is ignored
-
Tokens are not case sensitive
-
If there are repeated tokens in a file, the last token wins
Advanced configuration commands
-
FileTracingDir = { DIRPATH }
-
Default:
USE_RELATIVE_PATH
-
Custom log file directory. e.g. "C:\MyTraceDir" on Windows or "~/MyTraceDir" on macOS.
-
If DIRPATH == USE_RELATIVE_PATH then the output trace file directory will be created next to the target application.
-
Append = { true | false }
-
Default:
false
-
Append to file. If
true
, the output of this trace will be appended to any existing log file with the same name. Otherwise, this trace will overwrite an existing log file with the same name.
-
LogFileLimit = { LIMIT }
-
Default: no limit
-
Limits the number of log files kept around for this config file to the specified number.
-
If set to an integer value, DigiTrace will delete the oldest log file(s) until there are only N most recent log files in the output folder.
-
If you rename an output file so it does not have the standard prefix, it is never deleted by this option.
-
Does not work with the "append" option
-
TraceQueueSize = { small | medium | large }
-
Default:
small
-
This controls the amount of memory allocated to the trace queue. You probably won't need to change it.
-
BeQuiet = { true | false }
-
Default:
false
-
"Quiet" mode. If set to
true
, this configuration option makes all trace output occur without any decoration (i.e. no timestamps, no thread id, no process id, etc.).
-
This mode may be useful for some types of real-time vector tracing or for configuring formatted logs for post-processing with a text editor.
-
FileId = { FILEID }
-
Default: none
-
If set, this string is included in the filename created by DigiTrace for trace output files.
-
Does not work with the "append" option
-
Name = { NAME }
-
Default: none
-
If set, this string is included in every trace for all the facilities that are enabled in this config file.
-
You can have one of these per config file.
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:
-
In debug builds, this will happen each time the app comes to the foreground.
-
The API only does anything if something has changed in your config files that will result in different tracing of some sort. If nothing has changed, the overhead to make the call is < 1ms, and current tracing is not affected.
-
If something has changed, the changes are merged in to the existing config objects in memory. Active log files are not interrupted when possible. This takes around 200ms (mostly because of a sleep command that lets threads finish tracing things). Traces that happen in threads during this changeover will be dropped.
-
No code in the actual tracing commands was changed.
-
You can change any of the attributes of the trace facilities (priority level, file or console, etc).
-
You can add new config files on the fly, or if you start with no config file, you can add one on the fly.
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:
- DigiTrace is fully compatible with Pro Tools 8.0.3 and later. DigiTrace is installed by default with compatible Pro Tools shipping versions and with some Pro Tools Development Builds.
- DigiTrace is compatible with all versions of the DAE dish in the DSH environment. Tracing must be explicitly enabled in the dsh executable by placing a config.digitrace config file next to the executable.
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.