Attaching to a running process

Attaching to a running process#

ROCm Systems Profiler can attach to and profile an already running process using the rocprof-sys-attach executable. This capability is useful for profiling long-running applications, daemons, or processes that are difficult to restart with instrumentation.

Prerequisites#

Before starting with process attachment, you should ensure:

Attachment support is enabled by configuring the ROCP_TOOL_ATTACH=1 environment variable. Without this variable, attachment will fail.
```
# Start your application with attachment support enabled
ROCP_TOOL_ATTACH=1 ./my_application
```
This is not required if a version of rocprofiler-register built with ROCPROFILER_REGISTER_BUILD_DEFAULT_ATTACHMENT=ON is used.
The target process is compiled with debug symbols or frame pointers for meaningful profiling results.
The process is running with the appropriate permissions for attachment (see ptrace requirements).

When to use rocprof-sys-attach#

Use rocprof-sys-attach when:

The application is already running and cannot be easily restarted.
You want to profile a specific phase within a long‑running application.
The application is started by an external system (For example, job scheduler).
You need to attach profiling dynamically based on runtime conditions.

The rocprof-sys-attach executable#

View the help menu of rocprof-sys-attach using the -h or --help option:

$ rocprof-sys-attach --help
Usage: rocprof-sys-attach -p <pid> [OPTIONS]

Attach to a running process for profiling.

Options:
  -p <pid>             Process ID to attach to (required)
  -o, --output PATH    Output path for profiling results
  -F, --format FORMAT[,FORMAT,...]
                       Output format(s): perfetto, rocpd
  -h, --help           Show this help message

Environment variables:
  ROCPROFSYS_OUTPUT_PATH       Output directory for profiling data
  ROCPROFSYS_TRACE             Enable perfetto trace output
  ROCPROFSYS_USE_ROCPD         Enable rocpd database output
  ROCPROF_ATTACH_TOOL_LIBRARY  Path to the tool library

Once attached, press ENTER to detach from the process.

Command-line options#

-p <pid> (required)

The process ID of the running application to attach to. You can find the PID using tools like ps, pgrep, or top.

-o, --output PATH

Specifies the directory for writing the output of the profiling results. If not specified, the results are written to the default location (rocprof-sys-output/).

-F, --format FORMAT[,FORMAT,...]

Specifies the output format(s) for the profiling data. Multiple formats can be provided as a comma-separated list. Available formats are:

perfetto - Generates a Perfetto trace file (.pftrace) that can be visualized in the Perfetto UI.
rocpd - Generates a RocPD SQLite database file (.db) for programmatic analysis.

Basic usage#

Find the process ID of the running application:
```
$ pgrep -f my_application
12345
```
Attach to the process with basic profiling:
```
$ rocprof-sys-attach -p 12345
```
Wait for the desired profiling period you want to capture, then press ENTER to detach and finalize the profiling data.

Examples#

Some examples of process attachment are:

Attach with Perfetto trace output#

Generate a Perfetto trace file for visualization:

$ rocprof-sys-attach -p 12345 -F perfetto

After detaching, the trace file will be available at: rocprof-sys-output/<timestamp>/perfetto-trace-12345.pftrace

Attach with custom output path#

Specify a custom output directory:

$ rocprof-sys-attach -p 12345 -o /path/to/results -F perfetto

Attach with multiple output formats#

Generate both Perfetto trace and RocPD database:

$ rocprof-sys-attach -p 12345 -o ./profiling-results -F perfetto,rocpd

This generates:

./profiling-results/<timestamp>/perfetto-trace-12345.pftrace
./profiling-results/<timestamp>/rocpd-12345.db

Using environment variables#

You can also configure profiling using environment variables:

$ ROCPROFSYS_OUTPUT_PATH=/my/output ROCPROFSYS_TRACE=true rocprof-sys-attach -p 12345

Workflow example#

Here is a complete workflow for attaching to a running GPU application:

# Terminal 1: Start your application with attachment support enabled
$ ROCP_TOOL_ATTACH=1 ./my_gpu_application
[my_gpu_application] Starting computation...

# Terminal 2: Find the PID and attach
$ pgrep -f my_gpu_application
98765

$ rocprof-sys-attach -p 98765 -o ./results -F perfetto,rocpd
[rocprof-sys-attach] Using tool library: /opt/rocm/lib/librocprof-sys-dl.so
[rocprof-sys-attach] Output path: ./results
[rocprof-sys-attach] Output format: perfetto rocpd
[rocprof-sys-attach] Trying to attach to process 98765
[rocprof-sys-attach] Attached to process 98765. Press ENTER to detach.

# Let the application run for the profiling period...
# Press ENTER when ready to stop profiling

[rocprof-sys-attach] Detached from process 98765
[rocprof-sys-attach] Output written to: ./results
[rocprof-sys-attach]   - Perfetto trace: perfetto-trace-98765.pftrace
[rocprof-sys-attach]   - RocPD database: rocpd-98765.db

# View the trace in Perfetto UI
$ firefox https://ui.perfetto.dev
# Drag and drop the .pftrace file to visualize

Re-attaching to a process#

After detaching from a process, you can re-attach to the same PID to start a new profiling session. Each re-attach produces a separate output with its own timestamp directory.

# First profiling session
$ rocprof-sys-attach -p 98765 -o ./results -F perfetto
[rocprof-sys-attach] Attached to process 98765. Press ENTER to detach.
# Press ENTER to detach
[rocprof-sys-attach] Detached from process 98765

# Second profiling session (same PID)
$ rocprof-sys-attach -p 98765 -o ./results -F perfetto
[rocprof-sys-attach] Attached to process 98765. Press ENTER to detach.
# Press ENTER to detach
[rocprof-sys-attach] Detached from process 98765

Note

Configuration settings (environment variables, output format, etc.) are captured during the first attach and persist across re-attach sessions. Changing environment variables between sessions has no effect. To profile with different settings, restart the application.

Troubleshooting#

Troubleshooting examples for some common issues are:

Attachment fails immediately#

If attachment fails, ensure the target process was started with attachment support:

# The target process MUST be started with this environment variable
ROCP_TOOL_ATTACH=1 ./my_application

Without ROCP_TOOL_ATTACH=1, the target process does not initialize the attachment infrastructure and cannot be profiled dynamically.

Permission denied#

If you receive a permission error when attaching, ensure the following:

You have appropriate permissions to attach to the process (same user or root)

The ptrace scope allows attachment:

# Check current setting
$ cat /proc/sys/kernel/yama/ptrace_scope

# Temporarily allow attachment (requires root)
$ sudo sysctl kernel.yama.ptrace_scope=0

Process not found#

If the process cannot be found:

Verify the PID is correct: ps -p <pid>.
Ensure the process is still running.
Check if the process is in a different namespace (containers).

Attaching to a process in a container#

rocprof-sys-attach injects a tool library (librocprof-sys-dl.so) into the target process. The path must be valid in the target’s mount namespace (view of the filesystem), which can differ from the attaching process’ when the target runs in a container. rocprof-sys-attach picks the library in this order:

ROCPROF_ATTACH_TOOL_LIBRARY, if set.
The library from its own installation, if the target can see it at the same path.
The librocprof-sys-dl.so shipped with the ROCm installation the target process has loaded, found through that process’ own view of the filesystem.

If none of these is available in the target’s mount namespace, set ROCPROF_ATTACH_TOOL_LIBRARY to the absolute path of librocprof-sys-dl.so as seen by the target process before attaching:

# path of librocprof-sys-dl.so inside the target's own mount namespace
export ROCPROF_ATTACH_TOOL_LIBRARY=/opt/rocprofiler-systems/lib/librocprof-sys-dl.so
rocprof-sys-attach -p <pid>

rocprof-sys-attach validates the chosen path against the target’s mount namespace before attaching. If the library cannot be found there, attachment fails cleanly with a diagnostic instead of injecting a path the target cannot load.