DigiTrace Guide

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

On this page

• What is DigiTrace?
• DigiTrace quick start guide
• DigiTrace log files
• Configuring DigiTrace
• Real-time audio performance logging with DigiTrace
• Adding traces to an AAX plug-in
• Advanced DigiTrace configuration
• Compatibility
• Additional Information

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
• Configure DigiTrace for plain-text output
• Add tracing to a plug-in
• Configure DigiTrace for AAX plug-in logging

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 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 OS X 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.

Configure DigiTrace for AAX plug-in logging

To configure DigiTrace to print logs from AAX_TRACE or AAX_TRACE_RELEASE macros in AAX plug-ins, add the following line to the config.digitrace file for the application:

DTF_AAXPLUGINS=file@DTP_LOWEST

The config.digitrace file is a plain-text file that should be placed either directly next to the application executable or in the OS X application bundle's Resources directory. If a config.digitrace file does not already exist for the application then you can create it to enable DigiTrace.

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. The default location of this directory depends on the operating system and on which version of DigiTrace is being used:

• Pro Tools / DigiTrace 11.0 and later:
  ~/Library/Logs/Avid/ (OS X)
  C:\Program Files\Avid\Pro Tools\Logs (Windows)
• Pro Tools / DigiTrace 9.0 - 10.3:
  ~/Library/Logs/AvidLogFiles/ (OS X)
  C:\Users\[username]\AvidLogFiles\ (Windows 7)
  C:\Documents and Settings\[username]\AvidLogFiles\ (Windows XP)
• Pro Tools / DigiTrace 8.0.3 - 8.5:
  [Pro Tools application directory]/LogFiles/ (All configurations)

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 OS X 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.

• For basic real-time monitoring of a single file, use tail:
  tail -f /path/to/digitrace/logs/the_logfile.txt
• For real-time monitoring of the most recent file in the log file directory, use a combination of tail and ls:
  tail -f `ls -d -1 -rt /path/to/digitrace/logs/*.txt | tail -1`

digitrace__logfiles__monitoring__console

Console behavior is quite different between OS X 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.

OS X

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 columns consist of the following:

• 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

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:

• 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 audio 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.

Real-time audio 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 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.

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:

• 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.

For more information about tracing in release builds see Security concerns

digitrace__advancedlogging__macros__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

• 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 OS X.
  • 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.

Collaboration diagram for DigiTrace Guide: