Tracing Sync Framework Components

Sync Framework enables you to trace the execution of several components, which is useful during application debugging. For most of the Sync Framework components, tracing is performed at the native code level by using the Event Tracing for Windows (ETW) infrastructure. For more information about the ETW infrastructure, see Event Tracing.

Even if you develop against the managed version of an API, you still use ETW because the managed API is a thin wrapper over the native API. Sync Framework database providers do provide managed tracing that is based on the .NET Framework implementation. For more information, see How to: Trace the Synchronization Process.

Downloading and Using the Tracing Tools

The tracing tools that ETW requires are included in the Windows Support Tools, which are available for each version of Windows. For example, the tools for Windows XP SP2 are available at this Microsoft Download Center page. The tools that are relevant to Sync Framework tracing are described in the following table:

To view the output of a trace, you start a trace log, enable tracing, and then format the trace for viewing.

To start a trace logger

To start a trace logger, specify a logger name, a trace file name, and several parameters that control how the file is written: tracelog.exe -start <LoggerName> <LoggerParameters> -f <PathToEtlFile>. For example, the following command can be used:

tracelog.exe -start "Sync" -paged -b 32 -max 100 -cir 20 -ls -f %TEMP%\SyncFramework.etl

To enable tracing

To enable tracing, specify the GUID of the component to trace, a bit mask of flags that indicate which subcomponents to trace, and an integer that represents the level of tracing: tracelog.exe - enable <LoggerName> -guid <ComponentTracingId> -flags <Flags> -level <Level>. In this example, we enable tracing of the Sync Framework core component and all its subcomponents, with a tracing level of 4 (informational messages that include non-error cases):

tracelog.exe -enable "Sync" -guid #5978339c-8ab2-467e-bb85-8832659d5ed0 -flags 0xffff -level 4

For a complete list of options for Sync Framework, see Sync Framework Tracing Reference in this topic.

To format and view the trace file

To view a trace, flush the logger, and format the binary trace file by using the .tmf files that are available for Sync Framework from the Microsoft Download Center. Use commands similar to the following to view the trace from the "Sync" logger:

1. To flush the logger, execute tracelog.exe -flush "Sync".

2. Copy the .tmf files from the Sync Framework install path (Program Files\Microsoft SDKs\Microsoft Sync Framework\v2.0) to a working directory, such as %TEMP%\TMF.

3. To format the file, execute tracefmt.exe %TEMP%\SyncFramework.etl -p %TEMP%\TMF -o %TEMP%\SyncFrameworkTrace.txt.

4. To view the file, open %TEMP%\SyncFrameworkTrace.txt.

To stop tracing

To stop the "Sync" logger that we started earlier, execute tracelog.exe -stop "Sync".

Sync Framework Tracing Reference

The following table shows the GUIDs that represent each Sync Framework component:

Tracing flags

The following tables show the bit mask flags that can be passed to the -flags parameter of tracelog.exe to specify which subcomponents should be traced:

Core framework and runtime flags

Simple providers flags

Web synchronization components flags

Metadata storage service flags

File synchronization provider flags

Trace levels

The following table shows the trace levels that are used by Sync Framework. An increase in level represents an increase in logging verbosity, and the levels are cumulative. For example, a level 4 trace contains all of the information from levels 1-3 and additional information:

See Also

Concepts

Troubleshooting Sync Framework