Recording commands

To start a CPU performance capture, one of the three main recording commands can be used:

• run
• attach
• record

attach

The attach command will attach to a currently running process, or, when supported by the platform, to multiple running processes. For console platforms, you will always attach to the currently running application without the need to specify a specific process. For desktop platforms, like Windows, processes can be specified by name or process ID. The specific attach parameters depend on the platform, which are specified as a subcommand.

Examples:

Display all options and flags for attaching on Windows:

SuperluminalCmd attach windows --help

Attach to a single process on Windows by specifying process name:

SuperluminalCmd attach windows --process-name MyApplication

Attach to a single process on Windows by specifying process ID:

SuperluminalCmd attach windows --process-id 2045

Attach to multiple processes on Windows:

SuperluminalCmd attach windows --process-name MyApplication1 --process-name MyApplication2 --process-id 2045

run

The run command will launch an application and start recording immediately. The specific record parameters depend on the platform, which are specified as a subcommand. The path to the application and its parameters are always specified at the end of the command-line. This is to ensure that any parameters that are passed to the application will not clash with the parameters that are specified for the command-line tool.

Examples:

Display all options and flags for running an application on Windows:

SuperluminalCmd run windows --help

Run a program on Windows:

SuperluminalCmd run windows "c:\My Folder\MyApplication.exe"

Run a program on Windows with a different working folder, and pass parameters to MyApplication:

SuperluminalCmd run windows --working-dir "c:\My Folder\Data" "c:\My Folder\MyApplication.exe" --myparam 3

record

The record command will record everything that is currently running. For console platforms, this means that it will record the currently running application. For desktop platforms, like Windows, this will perform a system-wide capture. Specific processes can be selected when opening the capture file in Superluminal, or when using the resolve command.

Examples:

Display all options and flags for performing a system-wide capture on Windows:

SuperluminalCmd record windows --help

Perform a system-wide capture on windows:

SuperluminalCmd record windows

When a recording is created, it will produce a capture file with raw data that is platform-specific. It needs to be transformed into data that can be used in Superluminal, which is the resolving step. During the resolving step, any symbols are processed as well. The output will be a Superluminal session that contains all symbols that could be resolved, which can be transferred to other machines for analysis.

It is not necessarily needed to perform the resolve step by the command-line tool, as the Superluminal UI also accepts the platform-specific files and will perform the resolving when needed. It can still be convenient to perform this step in the command-line tool in cases where symbols are only available locally, but the analysis of the capture needs to be performed on a different machine. Another reason might be to perform the work of the resolving step on a server, instead of having to do it locally.

Resolving can be performed as part of the attach or run commands, and it can be performed as a separate step with the resolve command.

Examples:

Display all options and flags for resolving an '.etl' file on Windows:

SuperluminalCmd resolve windows --help

Run a program on Windows, and resolve it after the capture completes, using C:\SymbolCache for symbol cache:

SuperluminalCmd run windows --resolve --symbol-cache-dir "c:\SymbolCache" "c:\My Folder\MyApplication.exe"

Attach to "MyApplication" on Windows, and resolve it after the capture completes, using C:\SymbolCache for symbol cache:

SuperluminalCmd attach windows --process-name MyApplication --resolve --symbol-cache-dir "c:\SymbolCache"

Resolve an '.etl' capture file on Windows as a separate step, using C:\SymbolCache for symbol cache:

SuperluminalCmd resolve windows --symbol-cache-dir "c:\SymbolCache" "c:\My Folder\MyCapture.etl"

By default, all capture commands run in blocking mode, meaning that the command won't return until the capture is stopped. For integration in scripts and batch files, it is often convenient to be able to start a capture, do some work, and then stop a capture. The async mode is used specifically for those scenarios.

By specifying the --async-session option and a session name, the capture command will exit immediately after the capture is started. The capture will keep running so that other operations can be performed while capturing. The stop command will then stop the async capture session.

Example:

; Start a recording session named 'sl_session' and output to trace.etl
SuperluminalCmd record windows --async-session sl_session --capture-path ./trace.etl

; Do work here, for instance: run a number of processes in sequence
c:\MyBuild\MyProcess1.exe
c:\MyBuild\MyProcess2.exe
c:\MyBuild\MyGame.exe

; Stop the async session with the corresponding session name
SuperluminalCmd stop --async-session sl_session

; Optional: resolve the resulting capture file
SuperluminalCmd resolve windows --symbol-cache c:\SymbolCache ./trace.etl
								

The command-line tool is designed to be easily deployed to other machines without requiring a Superluminal license. This is convenient for recording on build machines or machines from people in the organization who want to make performance captures but don't perform any of the profiling work. An example is a QA department that makes performance captures, while the programming team can inspect the performance captures using the Superluminal UI.

The command-line tool is part of the Superluminal install itself. For easy deployment to remote machines, the make-redist command can be used, creating a tiny package that can be copied to other machines without the need to run an installer.

Examples:

Create a zip file of the currently installed SuperluminalCmd version:

SuperluminalCmd make-redist --output-zip ./SuperluminalCmd.zip

Output the files of the currently installed SuperluminalCmd version in directory ./SuperluminalCmd:

SuperluminalCmd make-redist --output-dir ./SuperluminalCmd"

By default, the deployment package will only contain the platforms that can be publically distributed and will not include any console platforms. If you are a registered console developer and have any console platforms installed, the --include-consoles option will be available. This option will include platforms like PlayStation® and Xbox, so that capturing for these platforms is also enabled. However, the resulting package may only be distributed internally within the company.

SuperluminalCmd make-redist --output-zip ./SuperluminalCmd.zip --include-consoles