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:
| Tracing tool | Description | Syntax reference |
|---|---|---|
Tracelog.exe |
Starts, stops, or enables trace logging. |
|
Tracefmt.exe |
Formats and displays trace messages from an event trace log file (.etl) or a real-time trace session. |
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:
To flush the logger, execute
tracelog.exe -flush "Sync".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.To format the file, execute
tracefmt.exe %TEMP%\SyncFramework.etl -p %TEMP%\TMF -o %TEMP%\SyncFrameworkTrace.txt.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:
| Component | Component tracing ID |
|---|---|
Core framework and runtime |
5978339c-8ab2-467e-bb85-8832659d5ed0 |
Simple providers |
69c896b3-e183-428d-9e30-4b519b156828 |
Web synchronization components |
0958c02f-01cb-4b28-badf-1431c83a931e |
Metadata storage service |
67161b7f-60ff-4368-832e-670f2327a7e4 |
File synchronization provider |
b5fac8e8-25e0-4468-926e-54cd8514f8a0 |
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
| Trace flag name | Bit mask | Description |
|---|---|---|
TRACE_MSG_KNOWLEDGE |
0x0001 |
Synchronization knowledge operations |
TRACE_MSG_SYNC_SERVICES |
0x0002 |
Synchronization services such as application synchronization services and provider synchronization services |
TRACE_MSG_SYNC_SESSION |
0x0004 |
Synchronization session and synchronization session state |
TRACE_MSG_CHANGE_APPLIER |
0x0008 |
The notifying change applier |
TRACE_MSG_CHANGE_BATCH |
0x0010 |
The change batch |
TRACE_MSG_CHANGE |
0x0020 |
The individual change |
TRACE_MSG_FILTER |
0x0040 |
Change filtering |
TRACE_MSG_IN_MEMORY_CONFLICT_LOG |
0x0080 |
The in-memory conflict log |
TRACE_MSG_CHANGE_APPLICATION_SERVICES |
0x0100 |
Advanced change application services |
Simple providers flags
| Trace flag name | Bit mask | Description |
|---|---|---|
TRACE_MSG_SIMPLESYNCWRAPPER |
0x0001 |
Simple providers (no subcomponents are defined) |
Web synchronization components flags
| Trace flag name | Bit mask | Description |
|---|---|---|
TRACE_MSG_FEEDSYNC |
0x0001 |
Web synchronization components (no subcomponents are defined) |
Metadata storage service flags
| Trace flag name | Bit mask | Description |
|---|---|---|
TRACE_MSG_METADATA_STORE |
0x0001 |
Metadata storage service (no subcomponents are defined) |
File synchronization provider flags
| Trace flag name | Bit mask | Description |
|---|---|---|
TRACE_MSG_FSP |
0x0001 |
File synchronization provider (no subcomponents are defined) |
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:
| Trace level | Value | Description |
|---|---|---|
TRACE_LEVEL_NONE |
0 |
No tracing |
TRACE_LEVEL_CRITICAL |
1 |
Abnormal exit or termination |
TRACE_LEVEL_ERROR |
2 |
Severe errors |
TRACE_LEVEL_WARNING |
3 |
Warnings that might reveal problems |
TRACE_LEVEL_INFORMATION |
4 |
Information that includes non-error cases |
TRACE_LEVEL_METADATA_INFORMATION |
5 |
Information about synchronization metadata |
TRACE_LEVEL_FUNCTION |
6 |
Information about when each function is entered and exited |