Using dotMemory Command-Line Profiler
Sometimes it is necessary to automate the process of gathering memory snapshots. For example, if you want to make profiling a part of your continuous integration builds (e.g., this can be a build step that performs profiling of your integration tests) or when you simply want to speed up profiling routines (e.g., when you regularly profile the same application and do not want to start the dotMemory user interface each time). For this purpose, dotMemory offers the dotMemory.exe command-line tool.
Note that the tool is distributed free of charge and does not require dotMemory to be installed. You can freely upload it to any computer to take memory snapshots of problematic applications.
get-snapshot- instantly get snapshot of a running app.
attach- attach the profiler to a running app and get snapshots by condition, using the API, or by sending commands to stdin.
start- start an app and get snapshots by condition, using the API, or by sending commands to stdin.
start-iis- start IIS and get snapshots by condition, using the API, or by sending commands to stdin.
dotMemory.exe help <command>
This section covers only most basic tool usage scenarios:
- Instantly get a snapshot of an already running application
- Run an application and get a snapshot by condition
- Run an application and get a snapshot by passing a message to stdin
- Run an application and control profiling using the API
- Attach to and profile an already running application
- Run and profile an ASP.NET application
Getting Snapshot of a Running Application
It is the most simple and demanded scenario. There are two ways of identifying the application you want to take snapshot from: via its PID or via its name.
To instantly get a snapshot of a running application by its PID (e.g., 6844):
--save-to-dir=C:\Snapshots- (optional) path to directory for saving a snapshot (more correctly, a workspace (.dmw file)). In this case, snapshot filename will be generated automatically. If you want to specify the filename by yourself, use the
6844- process PID (you can find it in Window Task Manager).
To instantly get a snapshot of a running application by its name:
MyApp- process name (you can find it in Windows Task Manager). If there are more than one process with such name, you can remove the ambiguity either with the
--with-max-mem- a process that consumes most of the memory will be profiled.
--all- all processes with the specified name will be profiled. dotMemory will take snapshots of all process (snapshot per process).
Starting Application and Getting Snapshots by Condition
Sometimes it may be necessary to track application memory consumption during a long time interval. In this case, you can start your application under profiling and get snapshots only in case a particular condition is satisfied: a periodic time interval ends or memory consumption increases by a specified value.
To start MyApp.exe and take snapshots periodically:
--trigger-timer=30s- time period for taking snapshots (30 s in our case).
C:\MyApp\MyApp.exe- path to the executable file of the profiled app.
MyAppArg1- (optional) argument of MyApp.exe. Note that if application argument starts with the dash (-) character, you can escape it using double dash (--). For example,
dotMemory.exe start --trigger-timer=30s C:\MyApp\MyApp.exe -- -MyAppArg1
To start MyApp.exe and take snapshots when memory consumption increases by the specified value:
--trigger-mem-inc=50%- a snapshot will be taken only when memory consumption of MyApp increases by 50%.
--trigger-delay=5s- a trigger will be enabled with the 5 s pause to skip the application startup phase.
Starting Application and Getting Snapshots Using stdin Messages
Sometimes it's necessary to have direct control over the profiling process, e.g., get a snapshot at some exact moment by a direct command. This can be done by sending special messages to stdin of dotMemory.exe.
To start MyApp.exe and control profiling using stdin messages:
- No additional arguments are required. You can start profiling as usual using
attachcommands. For example:
dotMemory.exe start c:\MyApp\MyApp.exe
dotMemory is able to inform you about how the profiling process is going by sending special service messages to stdout. This might be especially helpful in case you control profiling by some external script. To enable the support for stdout messages, run dotMemory with the
--service-outputoption, e.g.:dotMemory sends the following messages to stdout:
dotMemory.exe start --service-output c:\MyApp\MyApp.exe
- Get a snapshot by sending the following command to stdin: If
pidis specified, dotMemory will take a snapshot of the process with the specified PID. Otherwise, dotMemory will take snapshots of all profiled processes.
- To stop profiling and kill the profiled application, send the following command to stdin: Works for all profiling sessions started with
Starting Application and Getting Snapshots Using API
You also have the option to control profiling (get snapshots, detach from process, and so on) using the API.
To start MyApp.exe and control profiling with API:
Attaching to and Profiling Running Applications
If you want to profile an already running application and have full control over the profiling process (unlike the get-snapshot scenario), you should use the
attach command. It allows the profiler to attach to running processes (by PID or name as well as get-snapshot) and get snapshots using triggers, stdin commands, or the API. For instance, here is the example of how to profile a running app MyApp.exe and get snapshots using a trigger.
To attach to a running app and get snapshots periodically:
Running and Profiling IIS-hosted Web Applications
If you want to profile an ASP.NET web application that runs on IIS server, you should use the
start-iis command. After you run the command, IIS will be started under profiling (for more details on how IIS-hosted apps are profiled, refer toWeb Application Using IIS). Note that
start-iis supports the same ways of controlling profiling as the
start command: using triggers, stdin commands, and the API. For instance, here is the example of how to profile a web app and get snapshots using a trigger.
To run IIS under profiling and get snapshots periodically:
--open-url=localhost/myapp- URL of the profiled application that will be opened after you run profiling.
--use-browser=Chrome- browser that should be used to open the URL. If not provided, the default system browser will be used.