Concurrency Visualizer Command Line Utility (CVCollectionCmd)

  • Article

You can use the Concurrency Visualizer command-line utility (CVCollectionCmd.exe) to collect and process traces on machines that don't have Visual Studio. You can open the collected traces on a machine that has Visual Studio so that you can view them in the Concurrency Visualizer.

Installing and Deploying the Utility

To install from a Visual Studio DVD

  1. On the DVD, find the top-level folder named "Concurrency Visualizer."

  2. In this folder, run concvi_standalonecollection.exe.

To install from a Visual Studio Web Installation File

  1. Locate the installation file that you downloaded. The file name depends on the version of Visual Studio that you downloaded.

  2. Open a Command Prompt window and change to the directory where the installation file is located.

  3. Run the command <install file>/layout, where install file is the name of the file that you downloaded. The layout command creates a folder named "Concurrency Visualizer."

  4. In the "Concurrency Visualizer" folder, run concvi_standalonecollection.exe.

To deploy on a computer that doesn't have Visual Studio

  1. Locate concvi_standalonecollection.exe on a computer that has Visual Studio. (See the two previous procedures.)

  2. Copy concvi_standalonecollection.exe to the computer that doesn't have Visual Studio.

  3. Run concvi_standalonecollection.exe.

Commands and Parameters

You can get help on these commands and parameters by using:

CvCollectionCmd /?

Option

Description

Parameters

Return values

Query

Returns whether collection can be started.

None

0 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.

Launch

Runs 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.

Attach

Begins 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.

Detach

Stops 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.

Analyze

Analyzes 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.

LaunchArgs

Specifies the target executable arguments. This option applies to the Launch command only.

The command-line arguments to the application.

None.

Outdir

Specifies the directory in which to save trace files. Applies to the Launch and Attach commands.

A directory path or relative path.

None.

Process

Specifies 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.

Config

Specifies 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.

Customizing Configuration Settings

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

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:

Tag

Description

Values

Config

Demarcates the overall config file.

Must contain these elements:

  • MinorVersion

  • MajorVersion

MajorVersion

Specifies the major version of the config file.

Must be 1 for Visual Studio 2012 projects. If not 1, the utility will not work.

MinorVersion

Specifies the minor version of the config file.

Must be 0 for Visual Studio 2012 projects. If not 0, the utility will not work.

IncludeEnvSymbolPath

Sets a value that determines whether the environment symbol path (_NT_SYMBOL_PATH) is used.

  • True

  • False

DeleteEtlsAfterAnalysis

Sets a value that determines whether the ETL files are deleted when analysis completes.

  • True

  • False

SymbolPath

Specifies 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.

Markers

Contains the list of marker providers.

May contain zero or more MarkerProvider elements.

MarkerProvider

Specifies a single marker provider.

Must contain these elements:

  • Level

  • GUID

  • Name

Can contain these elements:

  • Categories

  • IsEnabled

Level

Sets the importance level of a MarkerProvider.

  • Low

  • Normal

  • High

  • Critical

  • Everything

Guid

The globally unique identifier of the ETW marker provider.

A GUID.

Name

Specifies the description of the marker provider.

A string.

Categories

Specifies the categories collected for the marker provider.

A comma-delimited string of numbers or ranges of numbers.

IsEnabled

Sets a value that determines whether the marker provider is enabled for collection.

  • True

  • False

FilterConfig

Specifies the list of configuration options of the ETW events that are filtered from collection.

May contain these elements:

  • CollectClrEvents

  • ClrCollectionOptions

  • CollectSampleEvents

  • CollectGpuEvents

  • CollectFileIO

CollectClrEvents

Set a value that determines whether CLR events are collected.

  • True

  • False

ClrCollectionOptions

Specifies 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

CollectSampleEvents

Sets a value that determines whether sample events are collected.

  • True

  • False

CollectGpuEvents

Sets a value that determines whether the events generated by DX are collected.

  • True

  • False

CollectFileIO

Sets a value that determines whether file I/O events are collected.

  • True

  • False

UserBufferSettings

Specifies the list of user buffer-settings parameters.

Must contain these elements:

  • BufferFlushTimer

  • BufferSize

  • MinimumBuffers

  • MaximumBuffers

KernelBufferSettings

Specifies the list of kernel buffer-settings parameters.

Must contain these elements:

  • BufferFlushTimer

  • BufferSize

  • MinimumBuffers

  • MaximumBuffers

BufferFlushTimer

Specifies the flush timer of the ETW buffers.

A positive integer.

BufferSize

Amount of memory that's allocated for each event-tracing session buffer, in kilobytes.

A number from 0 to 1024.

MinimumBuffers

The 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.

MaximumBuffers

Maximum number of buffers that are allocated for the buffer pool of the event-tracing session.

A number greater than or equal to MinimumBuffers.

JustMyCode

Specifies the list of Just My Code directories.

A list of zero or more MyCodeDirectory elements.

MyCodeDirectory

Specifies 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>