Export (0) Print
Expand All

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.

Tracelog Command Syntax

Tracefmt.exe

Formats and displays trace messages from an event trace log file (.etl) or a real-time trace session.

Tracefmt

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:

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

See Also

Show:
© 2014 Microsoft