Using Tracing Tools with VSS
To collect tracing information for the VSS infrastructure, you can use the VssTrace tool, the Logman tool, or the Tracelog tool. VssTrace is available in the Microsoft Windows Software Development Kit (SDK) and can be used to trace VSS applications on Windows 7 and later versions of the Windows operating system. Logman is a trace controller for trace events and performance counters; it can also be used to trace VSS applications on Windows 7 and later versions of the Windows operating system. Tracelog is included in the Windows Driver Kit (WDK).
To use tracing tools with Automated System Recovery (ASR), see Using Tracing Tools with ASR Applications.
Note
VssTrace, Logman, and Tracelog all require administrator privilege.
For information about each tool, see the following sections:
Using VssTrace
To run the VssTrace tool from the command line, use the following syntax:
vsstrace command-line-options
To display concise command-line help for the VssTrace tool, use the following syntax:
vsstrace -help
To display detailed command-line help for the VssTrace tool, use the following syntax:
vsstrace -help all
VssTrace Command-Line Options
The VssTrace tool uses the following command-line options:
-
-f Flags
-
Enable the modules whose flags are specified by the Flags bitmask. Each flag corresponds to a VSS module. If Flags is zero, no modules are enabled. Note that most modules are enabled by default. This option can be combined with the **+**Module option. For example, vsstrace -f 0 +WRITER +COORD disables tracing of all of the modules that are enabled by default and enables tracing of VSS writers and the VSS service. Alternatively, vsstrace +f 0xffff -COORD enables tracing of all modules except the VSS service.
Note
If you use the -f option together with the **+**Module option, the -f must appear before the **+**Module option.
The following table lists the module name and flag for each available module.
Module Flag Enabled by default Items traced EXCEPT 0x00000001 Yes C++ exception handling. COORD 0x00000002 Yes The VSS service, which is also called the VSS coordinator. SWPRV 0x00000004 Yes The VSS System Shadow Copy Provider service. BUCOMP 0x00000008 Yes The VSS requester and backup metadata processing. WRITER 0x00000010 Yes VSS writer operations and VSS hosted writer implementations, such as the Windows Registry writer. VSSAPI 0x00000020 Yes Miscellaneous functions of the VSS API exported by VSSAPI.DLL. HWDIAG 0x00000040 Yes VSS hardware provider infrastructure and operations. ADMIN 0x00000080 Yes VSS command line utilities such as VSSADMIN.EXE and DISKSHADOW.EXE. VSSUI 0x00000100 Yes The Shadow Copies for Shared Folders configuration user interface (UI). The UI is available only on Windows Server operating systems. TEST 0x00000200 Yes Not applicable. (This tracing module is reserved.) IOCTL 0x00000400 Yes Details of FSCTL and IOCTL operations that the VSS service has initiated by calling the DeviceIoControl function. GEN 0x00000800 Yes General VSS utility functions, such as allocators, string classes, and registry and volume operations. WRXML 0x00001000 No XML processing for writer metadata. This module has a very high level of noise. VSSXML 0x00002000 No XML processing base classes. This module has a very high level of noise. -
**+**Module
-
Enable the module specified by Module. More than one module can be enabled at a time. To list the available modules, type vsstrace –help modules at the command-line prompt.
-
-Module
-
Disable the module specified by Module. To list the available modules, type vsstrace –help modules at the command-line prompt.
-
+pid ProcessId
-
Enable the process specified by ProcessId. To enable all processes, use "*" for the value of ProcessId. More than one pid option can be specified at a time. The order of the options determines which processes are enabled or disabled. For example, to enable only the process whose process identifier is 0xe8c, use vsstrace -pid * +pid 0xe8c.
-
-pid ProcessId
-
Disable the process specified by ProcessId. To disable all processes, use "*" for the value of ProcessId. More than one pid option can be specified at a time. The order of the options determines which processes are enabled or disabled. For example, to disable all processes except the process whose process identifier is 0xe8c, use vsstrace -pid * +pid 0xe8c.
-
+tid ThreadId
-
Enable the thread specified by ThreadId. To enable all threads, use "*" for the value of ThreadId. More than one tid option can be specified at a time. The order of the options determines which threads are enabled or disabled. For example, to enable only the thread whose process identifier is 0x31a, use vsstrace -tid * +tid 0x31a.
-
-tid ThreadId
-
Disable the thread specified by ThreadId. To disable all threads, use "*" for the value of ThreadId. More than one tid option can be specified at a time. The order of the options determines which threads are enabled or disabled. For example, to disable all threads except the thread whose process identifier is 0x31a, use vsstrace -tid * +tid 0x31a.
-
-l Level
-
Use the tracing level specified by Level. The higher the level, the more verbose the trace output. Each level includes all of the lower levels. The default level is 170. The following levels are available.
Level Information included in the trace output 000 None 020 Fatal errors 030 Unhandled exceptions 040 Errors 050 Assertions 060 Warnings 080 Exception handling 100 Event Log activity 120 General information 140 Code flow 160 Function enter and exit 170 Function return values 180 Function parameters (terse) 190 Function parameters (verbose) 200 Verbose information level 1 210 Verbose information level 2 220 Verbose information level 3 230 Fast Code Level 1 240 Fast Code Level 2 250 Fast Code Level 3 255 All -
+indent
-
Indent the formatted trace output at each function and subfunction boundary.
-
-indent
-
Do not indent the formatted trace output.
-
-etl EtlFile
-
Convert the Logman output file specified by EtlFile into a readable text format.
-
-o OutputFile
-
Save the tracing information to the output file specified by OutputFile. For best performance, the output file should be located on a volume that is not part of the shadow copy.
-
-help HelpOption
-
Display the command-line help as specified by HelpOption. The valid HelpOption values are modules, levels, and all. Specifying modules causes the modules to be listed. Specifying levels causes the available levels to be listed. Specifying all causes detailed help to be displayed. If no options are used, concise help is displayed.
Using Logman
The following procedure describes how to use Logman with your VSS application.
To use Logman with your VSS application
Use the following command to start tracing:
logman start vss -o *x:\*vss.etl -ets -p {9138500e-3648-4edb-aa4c-859e9f7b7c38} 0xfff 170
Note
Replace "x:\" with the path to the directory where you would like the trace log file to be stored.
Use the following command to stop tracing:
logman stop vss -ets
The trace log file is *x:\*vss.etl.
For more information about the Logman tool, see Logman.
Using Tracelog
The following procedure describes how to use Tracelog.
To use Tracelog
Create a text file named vss.ctl that contains only the following text:
9138500e-3648-4edb-aa4c-859e9f7b7c38 vss
Use the following command to start tracing:
tracelog -start vss -f *x:\*vss.etl -guid vss.ctl -flag 0xff -level 0xaa
Note
Replace "x:\" with the path to the directory where you would like the trace log file to be stored.
Use the following command to stop tracing:
tracelog -stop vss
The trace log file is *x:\*vss.etl.
For more information about the Tracelog tool, see Tracelog.
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for