Concurrency Visualizer Command-Line Utility (CVCollectionCmd)

 

For the latest documentation on Visual Studio 2017 RC, see Visual Studio 2017 RC Documentation.

You can use the Concurrency Visualizer command-line utility (CVCollectionCmd.exe) to collect traces from the command line so that you can view them in the Concurrency Visualizer for Visual Studio . The ools can be used on computers that do not have Visual Studio installed.

System_CAPS_ICON_note.jpg Note

Starting in Visual Studio 2013, the Concurrency Visualizer is an optional extension. (Previously it had been included in Visual Studio.) You can download the Concurrency Visualizer Collection Tools for Visual Studio 2015 from the Download Center.

To download and install the command-line utility, go to Concurrency Visualizer Collection Tools for Visual Studio 2015 and follow the instructions. By default, CVCollectionCmd.exe is installed in %ProgramFiles%\Microsoft Concurrency Visualizer Collection Tools\ (%ProgramFiles(x86)%\Microsoft Concurrency Visualizer Collection Tools\ on x64 computers).

You can collect a trace by starting the app with CVCollectionCmd, or by attaching to it. See the command reference below for your options. For example

<Path>CVCollectionCmd /launch c:\myapp\myapp.exe /outdir c:\myapp\data  

To get help about the commands and parameters in the command-line utility, type this at the command prompt:

CvCollectionCmd /?

OptionDescriptionParametersReturn values
QueryReturns whether collection can be started.None0 if collection is ready to start.

1 if collection is already in progress.

2 if collection isn’t in progress, but one or more of the required ETW sessions is already enabled.
LaunchRuns the specified process under the Concurrency Visualizer.The path of the executable.0 if the run succeeded.

1 if the run failed because the target application couldn’t be started.

13 if the run failed because CVCollectionCmd has insufficient permissions to write to the specified output directory.
AttachBegins collecting a system-wide trace; otherwise, attaches to a process if one is specified.None.0 if attachment succeeded.

1 if attachment failed because the specified process is invalid or ambiguous.

13 if the attachment failed because CVCollectionCmd has insufficient permissions to write to the specified output directory.
DetachStops collection.None.0 if detachment succeeded.

1 if detachment failed because collection is not currently in progress.

2 if detachment failed because collection could not be stopped.
AnalyzeAnalyzes the specified trace.The full path of the CVTrace file.0 if analysis succeeded.

1 if analysis cannot start because the specified trace was system-wide, but no target process was specified.

2 if analysis cannot start because the trace was not system-wide and a process was specified.

3 if analysis failed because the specified process is invalid.

4 if analysis failed because the specified CVTrace file is invalid.
LaunchArgsSpecifies the target executable arguments. This option applies to the Launch command only.The command-line arguments to the application.None.
OutdirSpecifies the directory in which to save trace files. Applies to the Launch and Attach commands.A directory path or relative path.None.
ProcessSpecifies the process to attach to when the Attach command is executed, or the process in a trace to analyze when the Analyze command is executed. Applies to the Attach and Analyze commands.The PID or the name of the process.None.
ConfigSpecifies the path of the configuration file, if you want collection settings other than the defaults. Applies to the Launch, Attach, and Analyze commands.The directory path or relative path of the XML configuration file.None.

If you use CVCollectionCmd to collect traces and you want to customize the collection settings, then use a configuration file to specify them.

System_CAPS_ICON_note.jpg Note

When you use Visual Studio to collect traces, don't directly modify the configuration file. Instead, use the Advanced Settings dialog box to modify settings.

To modify collection settings, create a configuration file on the machine where you will run the CVCollectionCmd utility. You can create the configuration file from scratch, or you can copy the configuration file on the computer that has Visual Studio installed and modify that. The file is named UserConfig.xml and is located in the Local AppData folder. When you run the utility, use the Config option in conjunction with the Launch, Attach, or Analyze command. In the parameter that's associated with the Config option, specify the path of the configuration file.

Configuration File Tags

The configuration file is XML-based. Here are the valid tags and values:

TagDescriptionValues
ConfigDemarcates the overall config file.Must contain these elements:

- MinorVersion
- MajorVersion
MajorVersionSpecifies the major version of the config file.Must be 1 for Visual Studio 2012 projects. If not 1, the utility will not work.
MinorVersionSpecifies the minor version of the config file.Must be 0 for Visual Studio 2012 projects. If not 0, the utility will not work.
IncludeEnvSymbolPathSets a value that determines whether the environment symbol path (_NT_SYMBOL_PATH) is used.- True
- False
DeleteEtlsAfterAnalysisSets a value that determines whether the ETL files are deleted when analysis completes.- True
- False
SymbolPathSpecifies the path of the symbol server. For more information, see Use the Microsoft Symbol Server to obtain debug symbol files.A directory name or URL.
MarkersContains the list of marker providers.May contain zero or more MarkerProvider elements.
MarkerProviderSpecifies a single marker provider.Must contain these elements:

- Level
- GUID
- Name

Can contain these elements:

- Categories
- IsEnabled
LevelSets the importance level of a MarkerProvider.- Low
- Normal
- High
- Critical
- Everything
GuidThe globally unique identifier of the ETW marker provider.A GUID.
NameSpecifies the description of the marker provider.A string.
CategoriesSpecifies the categories collected for the marker provider.A comma-delimited string of numbers or ranges of numbers.
IsEnabledSets a value that determines whether the marker provider is enabled for collection.- True
- False
FilterConfigSpecifies the list of configuration options of the ETW events that are filtered from collection.May contain these elements:

- CollectClrEvents
- ClrCollectionOptions
- CollectSampleEvents
- CollectGpuEvents
- CollectFileIO
CollectClrEventsSet a value that determines whether CLR events are collected.- True
- False
ClrCollectionOptionsSpecifies whether to collect CLR events for native apps, and whether to collect NGEN rundown events.May contain one, both, or none of these values:

- CollectForNative
- DisableNGenRundown
CollectSampleEventsSets a value that determines whether sample events are collected.- True
- False
CollectGpuEventsSets a value that determines whether the events generated by DX are collected.- True
- False
CollectFileIOSets a value that determines whether file I/O events are collected.- True
- False
UserBufferSettingsSpecifies the list of user buffer-settings parameters.Must contain these elements:

- BufferFlushTimer
- BufferSize
- MinimumBuffers
- MaximumBuffers
KernelBufferSettingsSpecifies the list of kernel buffer-settings parameters.Must contain these elements:

- BufferFlushTimer
- BufferSize
- MinimumBuffers
- MaximumBuffers
BufferFlushTimerSpecifies the flush timer of the ETW buffers.A positive integer.
BufferSizeAmount of memory that's allocated for each event-tracing session buffer, in kilobytes.A number from 0 to 1024.
MinimumBuffersThe minimum number of buffers that are allocated for the buffer pool of the event-tracing session.A positive integer greater than or equal to twice the number of logical cores.
MaximumBuffersMaximum number of buffers that are allocated for the buffer pool of the event-tracing session.A number greater than or equal to MinimumBuffers.
JustMyCodeSpecifies the list of Just My Code directories.A list of zero or more MyCodeDirectory elements.
MyCodeDirectorySpecifies a directory that contains your code.An absolute path.

Example

Instead of creating a configuration file from the beginning, you can copy the following example and then modify it to meet your requirements.

<?xml version="1.0"?>  
<LocalConfig xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" MajorVersion="1" MinorVersion="0">  
  
  <IncludeEnvSymbolPath>true</IncludeEnvSymbolPath>  
  
  <DeleteEtlsAfterAnalysis>true</DeleteEtlsAfterAnalysis>  
  
  <TraceLocation>C:\traces</TraceLocation>  
  
  <SymbolPath>http://symweb</SymbolPath>  
  
  <Markers>  
    <MarkerProvider Name="Default" Guid="8d4925ab-505a-483b-a7e0-6f824a07a6f0" Level="Low" />  
    <MarkerProvider Name="TPL" Guid="2e5dba47-a3d2-4d16-8ee0-6671ffdcd7b5" Level="Normal" />  
    <MarkerProvider Name="TPL Dataflow" Guid="16f53577-e41d-43d4-b47e-c17025bf4025" Level="Normal" />  
    <MarkerProvider Name="TPL Synchronization" Guid="ec631d38-466b-4290-9306-834971ba0217" Level="Normal" />  
    <MarkerProvider Name="PLINQ" Guid="159eeeec-4a14-4418-a8fe-faabcd987887" Level="Normal" />  
    <MarkerProvider Name="Concurrency Runtime" Guid="f7b697a3-4db5-4d3b-be71-c4d284e6592f" Level="Normal" />  
    <MarkerProvider Name="Scenario Markers" Guid="fb9244c9-f23a-4966-8a9c-97a51f8c355b" Level="Low" />  
  
    <!-- The IsEnabled and Categories elements are optional -->  
    <MarkerProvider Name="myMarker1" Guid="d0dbb3a3-895c-4ce6-96d9-28f69d664dc3" Level="Critical" IsEnabled="false" Categories="0,1,3-5,8" />  
    <MarkerProvider Name="myMarker2" Guid="03452127-a617-4302-9e30-c0d10442e4ee" Level="Low" IsEnabled="false" Categories="0,1,3-5,8-10,11-13" />  
  </Markers>  
  
  <FilterConfig>  
    <CollectClrEvents>true</CollectClrEvents>  
    <ClrCollectionOptions>CollectForNative DisableNGenRundown</ClrCollectionOptions>  
    <CollectSampleEvents>true</CollectSampleEvents>  
    <CollectGpuEvents>true</CollectGpuEvents>  
    <CollectFileIO>true</CollectFileIO>  
  </FilterConfig>  
  
  <UserBufferSettings>  
    <BufferFlushTimer>0</BufferFlushTimer>  
    <BufferSize>256</BufferSize>  
    <MinimumBuffers>512</MinimumBuffers>  
    <MaximumBuffers>1024</MaximumBuffers>  
  </UserBufferSettings>  
  
  <KernelBufferSettings>  
    <BufferFlushTimer>0</BufferFlushTimer>  
    <BufferSize>256</BufferSize>  
    <MinimumBuffers>512</MinimumBuffers>  
    <MaximumBuffers>1024</MaximumBuffers>  
  </KernelBufferSettings>  
  
  <!-- List of MyCodeDirectory directories -->  
  <JustMyCode>  
    <MyCodeDirectory>C:\myBinaries1</MyCodeDirectory>  
    <MyCodeDirectory>C:\myBinaries2</MyCodeDirectory>  
  </JustMyCode>  
</LocalConfig>  
  

Show: