Configuration

  • Article

[This Tracing API is available for use in the operating systems listed in the Requirements section. It may be altered or unavailable in subsequent versions. Instead use the Event Tracing API.]

In order to enable console tracing, the value \EnableConsoleTracing must exist under the registry key

HKEY_LOCAL_MACHINE
     SOFTWARE
          MICROSOFT
               TRACING

and be nonzero. If this value does not exist, or is zero, console tracing is disabled. This value is read when Rtutils.dll is loaded; changes to this value after Rtutils.dll is already loaded have no effect until the DLL is unloaded and loaded again.

In addition to the preceding global value, the registry may also contain values for individual clients. When a client xyz calls TraceRegister, tracing searches under the registry key

HKEY_LOCAL_MACHINE
     SOFTWARE
          MICROSOFT
               TRACING
                    XYZ

for the following values:

  • \EnableConsoleTracing: This is a REG_DWORD that defaults to zero; tracing to the console is enabled if this value is nonzero.

  • \EnableFileTracing: This is a REG_DWORD that defaults to zero; tracing to a file named XYZ.LOG is enabled if this value is nonzero.

  • \ConsoleTracingMask: This is a REG_DWORD that defaults to 0xFFFF0000; the bits in the high-order word correspond to components in the client. If a call to one of the extended output functions has the flag TRACE_USE_MASK set, this registry value is compared against the high-order word of the flag passed to the output function, to decide whether or not to send the output to the console.

  • \FileTracingMask: This is a REG_DWORD that defaults to 0xFFFF0000; it operates similarly to \ConsoleTracingMask.

  • \MaxFileSize: This is a REG_DWORD that defaults to 0x10000; this is the maximum size a tracing file can grow to before it is renamed.

  • \FileDirectory: This is a REG_EXPAND_SZ that defaults to:

    %ALLUSERSPROFILE%
         Application Data
              Microsoft
                   Windows NT
                        TracingLogs

    This is the directory in which the tracing file is created.

The defaults are used only if the key is found or is created, but some values are absent from the key. If the registry key is not found and cannot be created, the call to TraceRegister fails.

Alternatively, a client xyz could call TraceRegisterEx, which takes a flag allowing the caller to specify the settings to use. Thus, a client could use tracing without creating any key in the registry. For instance,

    TraceRegisterEx("xyz", TRACE_USE_CONSOLE);

would register the client "xyz" to use the console for tracing, and the tracing API would not attempt to read the registry key for the client. Similarly,

    TraceRegisterEx("abc", TRACE_USE_FILE);

would register the client abc to use a file for tracing, bypassing the registry key for the client. However, for console tracing, using TraceRegisterEx still requires that the global \EnableConsoleTracing value exist under

HKEY_LOCAL_MACHINE
     SOFTWARE
          MICROSOFT
               TRACING

and be nonzero.