Use dotMemory Command-Line Profiler

You can use the dotMemory command-line profiler to profile any .NET or .NET Core application (including an already running one) and take memory snapshots.

The tool comes in handy in multiple scenarios:

Profiling an application on a remote server
For example, this may be the case when it is not possible to install the standalone dotMemory to a server.
Automating the process of gathering memory snapshots
For example, if you want to make profiling a part of your continuous integration builds: this can be a build step that performs profiling of your integration tests.
Speeding up profiling routines
For example, when you regularly profile the same application and do not want to start the dotMemory user interface each time.

Distribution

The tool is distributed free of charge as a .zip archive or NuGet package (Windows, Linux, macOS) and doesn't require installing dotMemory. You can freely upload it to any computer to take memory snapshots of problematic applications.

Main profiler commands

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-net-core - start a .NET Core app and get snapshots by condition, using the API, or by sending commands to stdin.
start-iis - (Windows only) start IIS and get snapshots by condition, using the API, or by sending commands to stdin.
start-iis-express - (Windows only) start IIS Express-hosted web application under profiling.
start-windows-service - (Windows only) (re)start managed Windows service under profiling and get memory snapshot by condition or using the API.
start-wcf-service - (Windows only) (re)start WCF host with specified WCF Service Library under profiling and get memory snapshot by condition or using the API.
start-winrt - (Windows only) start WinRT application under profiling and get memory snapshot by condition or using the API.
profile-new-processes - (Windows only) profile any managed application that is launched after executing this command.
list-iis-express - (Windows only) show the list of available IIS Express installations.
list-wcf-host - (Windows only) show the list of available WCF hosts.
list-winrt - (Windows only) show the list of available WinRT applications.

For the detailed information on a particular command, run: dotMemory.exe help <command> (Windows), ./dotMemory.sh help <command> (Linux, macOS).

Get snapshot of a running application

It is the simplest and most demanded scenario. All you need is tell dotMemory which application you want to profile. You can do this in two ways: by application name, or by PID.

To instantly get a snapshot of a running application by its PID (e.g., 6844):

Run the command:
dotMemory.exe get-snapshot 6844 --save-to-dir=C:\Snapshots

Here:

--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 --save-to-file option.
6844 - process PID (you can find it in Window Task Manager).

To instantly get a snapshot of a running application by its PID (e.g., 6844):

Run the command:
./dotMemory.sh get-snapshot 6844 --save-to-dir=~/Snapshots

Here:

--save-to-dir=~/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 --save-to-file option.
6844 - process PID (you can find it using the ps system command).

To instantly get a snapshot of a running application by its name

Run the command:
dotMemory.exe get-snapshot MyApp --with-max-mem
or
dotMemory.exe get-snapshot MyApp --all

Here:

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 or --all option.
--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).

To instantly get a snapshot of a running application by its name

Run the command:
./dotMemory.sh get-snapshot MyApp --with-max-mem
or
./dotMemory.sh get-snapshot MyApp --all

Here:

MyApp - process name (you can find it using the ps system command). If there are more than one process with such a name, you can remove the ambiguity either with the --with-max-mem or --all option.
--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).

Start application and get snapshots on 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

Run the command:
dotMemory.exe start --trigger-timer=30s C:\MyApp\MyApp.exe MyAppArg1

Here:

--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 and take snapshots periodically

Run the command:
./dotMemory.sh start --trigger-timer=30s ~/MyApp/MyApp my-app-arg1

Here:

--trigger-timer=30s - time period for taking snapshots (30 s in our case).
~/MyApp/MyApp - path to the executable file of the profiled app.
my-app-arg1 - (optional) argument of MyApp. Note that if application argument starts with the dash (-) character, you can escape it using double dash (--). For example:
./dotMemory.sh start --trigger-timer=30s ~/MyApp/MyApp -- -my-app-arg1

To start MyApp.exe and take snapshots when memory consumption increases by the specified value

Run the command:
dotMemory.exe start --trigger-mem-inc=50% --trigger-delay=5s C:\MyApp\MyApp.exe

Here:

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

To start MyApp and take snapshots when memory consumption increases by the specified value

Run the command:
./dotMemory.sh start --trigger-mem-inc=50% --trigger-delay=5s ~/MyApp/MyApp

Here:

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

Sometimes, you may want to get a snapshot immediately right after the start of the profiled application. For example, you can use this snapshot as a base for comparison.

To start MyApp.exe and take a snapshot right after the profiler is initialized

Run the command:
dotMemory.exe start --trigger-on-activation C:\MyApp\MyApp.exe

Here:

--trigger-on-activation - a snapshot will be taken immediately once the profiler is initialized. Note that if --trigger-delay is set, --trigger-on-activation will wait for this delay.

To start MyApp and take a snapshot right after the profiler is initialized

Run the command:
./dotMemory.sh start --trigger-on-activation ~/MyApp/MyApp

Here:

--trigger-on-activation - a snapshot will be taken immediately once the profiler is initialized. Note that if --trigger-delay is set, --trigger-on-activation will wait for this delay.

Start application and get snapshots using stdin messages

Sometimes it's necessary to have direct control over the profiling process, for example, get a snapshot at some exact moment by a direct command. This can be done by sending special messages to stdin of the command-line profiler.

Important notes:

Messages sent to stdin must always start with a new line and end with a carriage return.
Both stdin and stdout messages have a format of a JSON array, for example, ##dotMemory["get-snapshot", {pid:1234}]
Instead of sending messages to stdin, you can write them to a file. To specify file location, use the --service-input=path\to\file.svc parameter. The message format is the same as for stdin.

To start MyApp.exe and control profiling using stdin messages

No additional arguments are required. You can start profiling as usual using attach, or any of the start commands. 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 support for stdout messages, run dotMemory with the --service-output option, for example:
dotMemory.exe start --service-output C:\MyApp\MyApp.exe
dotMemory sends the following messages to stdout:
- Start of the profiling session
  ##dotMemory["connected", {pid: 1234}]
- Saving the snapshot
  ##dotMemory["workspace-saved", {path: "..."}]
Get a snapshot by sending the following command to stdin:
##dotMemory["get-snapshot", {pid:1234}]
If pid is 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:
##dotMemory["disconnect"]
Works for all profiling sessions started with attach of any of the start commands.

To start MyApp and control profiling using stdin messages

No additional arguments are required. You can start profiling as usual using attach, or any of the start commands. For example:
./dotMemory.sh start ~/MyApp/MyApp
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 support for stdout messages, run dotMemory with the --service-output option, for example:
./dotMemory.sh start --service-output ~/MyApp/MyApp
dotMemory sends the following messages to stdout:
- Start of the profiling session
  ##dotMemory["connected", {pid: 1234}]
- Saving the snapshot
  ##dotMemory["workspace-saved", {path: "..."}]
Get a snapshot by sending the following command to stdin:
##dotMemory["get-snapshot", {pid:1234}]
If pid is 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:
##dotMemory["disconnect"]
Works for all profiling sessions started with attach of any of the start commands.

Start application and get 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

Run the command:
dotMemory.exe start --use-api C:\MyApp\MyApp.exe

To start MyApp and control profiling with API

Run the command:
./dotMemory.sh start --use-api ~/MyApp/MyApp

Attach to and profile 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 lets 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 and get snapshots using a trigger.

To attach to a running app and get snapshots periodically

Run the command:
dotMemory.exe attach MyApp.exe --trigger-timer=30s

To attach to a running app and get snapshots periodically

Run the command:
./dotMemory.sh attach MyApp --trigger-timer=30s

(Windows only) Run and profile 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 information about how IIS-hosted apps are profiled, refer to Profile Web Application on IIS Server). 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

Run the command:
dotMemory.exe start-iis --trigger-timer=30s --open-url=localhost/myapp --use-browser=Chrome

Here:

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

Last modified: 24 July 2024