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.
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.
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).
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.
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).
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 theps
system command).
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).
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 theps
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).
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.
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 - path to the executable file of the profiled app.\MyApp.exe 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
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 - path to the executable file of the profiled app./MyApp 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
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.
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.
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.
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.
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.
No additional arguments are required. You can start profiling as usual using
attach
, or any of thestart
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 thestart
commands.
No additional arguments are required. You can start profiling as usual using
attach
, or any of thestart
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 thestart
commands.
You also have the option to control profiling (get snapshots, detach from process, and so on) using the API.
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.
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.
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.