Share via

Basic Command Line Profiling

  • Article

           Hey all, It's been a little while since my last post as things have been (and continue to be) pretty busy for me. Recently I've been working on some TechNotes (~1000 word mini articles) that will be published up on MSDN. While most of these I have been converting from blog entries there have been a few original ones sprinkled in there. Below is a TechNote I wrote about basic profiling from the command line, if you are looking for "Hello World" for using the profiler tools from the command line this is the article for you:

Profiling applications from the command line

Included with Visual Studio Team System 2005 Developer and Team Suite Editions is a powerful new performance profiler tool. This tool integrates seamlessly with the IDE to allow you to profile native and managed executables, assemblies and ASP.net websites. Also, we provide a selection of analysis views to help you dig down into the profiling data to isolate the performance issues in your applications. While we have worked hard at getting the IDE integration right, we also realize that many users will want and need to use our tools outside of the Visual Studio environment. For example, if you want to add automated performance profiling to your build or test process you will not be able to use the Visual Studio integration. To help you with this we have provided a series of command line tools to allow you to use the full functionality of the profiler outside of the IDE. This TechNote will give you a run down of these tools by showing you how to use them in some basic profiling scenarios and then by covering some advanced options for each of the tools. The profiler supports both sampling (where we take a look at program state in some periodic cycle) and instrumentation (where we insert code into the binaries to catch every function entry and exit) modes so we will first look at using both of these mode from the command line. The various tools that we use in these walkthroughs can be found in the Microsoft Visual Studio 8\Team Tools\Performance Tools directory if you have installed VSTS for Developers or Team Suite editions.

 

Basic command line sampling profiling:

The first step in this process is only needed if you are profiling a managed application. If you are, then you need to first set up the correct environmental variables so that the sampling profiler can attach to the managed program:

 

VsPerfCLREnv /sampleon

If you want to quickly profile an application in sampling mode you can just use the following command line:

 

VsPerfCmd /start:sample /output:Report.vsp /launch:MyApp.exe

This will do the following things: start up the monitor in sampling mode (the monitor writes collected profiling data to the report file), directs the output to the file Report.vsp, launches MyApp.exe and attaches the monitor to MyApp.exe. After you have finished your profiling scenario with MyApp.exe (which was automatically launched by the above command line) you need to shut down the monitor with the following command:

 

VsPerfCmd /shutdown

This will end data collection, kill any processes still attached to the monitor and finish writing all the data to Report.vsp. Now you can open up the Report.vsp file in Visual Studio to analyze it.

 

If you are done with profiling you will want to reset the environmental variables that allow for attaching to managed applications.

 

VSPerfCLREnv /off

 

Basic command line instrumentation profiling:

As with sampling, if you are profiling a managed application with instrumentation you need to set up the correct environmental variables to allow the profiler to attach to the instrumented process:

 

VSPerfCLREnv /traceon

When doing instrumentation profiling we first need to instrument (insert our code probes) into all of the assemblies that you wish to collect data on. The example below shows how to instrument an assembly using the VsInstr.exe tool:

 

VsInstr MyApp.exe

By default we will save a non-instrumented backup of your file with the name MyApp.orig.exe in the same directory. Next, we need to start up the monitor in instrumentation (trace) mode.

 

VsPerfCmd /start:trace /output:Report.vsp

Now that the monitor is started in trace mode we just need to run the instrumented MyApp.exe to collect data. Unlike sampling mode we cannot launch the application at the same time as the monitor so we need to run it in a separate step. After we have run our profiling scenario with MyApp.exe we need to stop collection and create our report file.

 

VsPerfCmd /shutdown

Now we will have an instrumentation profiling report that we can open for analysis in the IDE.

 

We have already looked at basic cases for sampling and instrumentation, however if you want to really exercise the command line tools you may need to go deeper with some of the advanced options on the tools.

 

VsPerfMon:

VsPerfMon is the command line tool responsible for starting up and controlling the output from the profiling monitor. In the above examples we used VsPerfCmd helper functions to start up the monitor but if you are doing advanced profiling it can be good to know how to use VsPerfMon. The only real options for VsPerfMon are specifying the collection mode (sampling, trace or coverage), directing the output to a specific report file and allowing client access to the monitor from a specific account.

 

When you start up VsPerfMon from the command line it will run in that command window, so you will need to open up another command window to run your application and to shutdown the monitor. To close down the monitor you just need to use the VsPerfCmd /shutdown command from any other open command window. This will stop data collection and finalize the report file.

 

VsInstr:

VsInstr is the tool that controls instrumentation for adding our probes to assemblies so that we can collect function entries and exits or so that we can collect code coverage information. If you want to instrument an assembly for a code coverage collection run you just need to pass in the /coverage switch when calling VsInstr on the assembly. Also, you can use the /outputpath option to direct the instrumented image to be placed in a different directory. This can be useful if you are integrating instrumentation profiling with an automated build or testing process so that you can keep all of your instrumented binaries in a separate location from your original binaries. VsInstr also contains a collection of limiting functions that allow you to restrict data collection only to specific functions or code paths within the assembly. This can be necessary as instrumentation collects a great deal of data and often needs to be limited to be useful for diagnostics.

 

VsPerfCmd:

As seem in the above short walkthroughs VsPerfCmd wraps the functionality of VsPerfMon and adds on some helpful functions for many profiling scenarios. You can use the /start and /output switches to control the profiling mode and output path functions of VsPerfMon. If you are running batch processes the /shutdown[:n] command can come in handy. This function waits for all the processes (for up to time n) that are being profiled to shutdown then it automatically shuts the monitor down and waits for the shutdown of the monitor to complete before returning, essentially acting as an automatic /shutdown call when you are done profiling. If the monitor is running in sampling collection mode you can use the /attach and /detach function of VsPerfCommand to start and stop collecting profiling data on any running processes. This is useful if you want to do sampling profiling on a restricted scenario for some process. For example if you do not want to collect any information on startup you can start the application and then attach to it when initialization is finished. If you want to profile an applications entire runtime using sampling you can use the /launch option to automatically launch and attach to an application. VsPerfCmd also controls the starting, stopping and installation of the VsPerfDrv driver that is needed for all profiling scenarios.

 

VsPerfReport:

This tool is what you will use if you want to analyze data from the report files without using the IDE analysis tools. By passing in options to the /summary switch you can create different comma separated value report files that you can look at in excel or your editor of choice. Also, by adding the /XML option to VsPerfReport you will output the summary reports as XML what you can then view with your own viewer or XSLT transform.

Comments