Environment variables for custom tools

Environment variables for custom tools#

This page documents the environment variables that affect a custom tool built against ROCprofiler-SDK — that is, a shared library that implements rocprofiler_configure (see ROCprofiler-SDK tool library). It does not cover the ROCPROF_* variables consumed by rocprofv3; those are documented separately in the rocprofv3 how-to guides.

Only variables that are part of the public custom-tool contract are listed here. Internal SDK tuning knobs and development/test overrides are intentionally omitted: they are subject to change without notice and should not be relied on by external tools.

Variables are grouped by the role they play in a custom tool’s lifecycle.

Tool discovery and loading#

These variables control how ROCprofiler-SDK locates and loads your tool library. At least one of the following mechanisms must be configured before the first ROCm runtime call so that registration can discover the tool. With ROCP_TOOL_LIBRARIES the library is dlopened by the SDK during registration (triggered by the first ROCm runtime call); with LD_PRELOAD the library is mapped by the dynamic loader at process start.

Variable

Default

Description

ROCP_TOOL_LIBRARIES

(unset)

Colon-separated list of absolute paths to shared libraries that export rocprofiler_configure. ROCprofiler-SDK dlopens each entry and invokes its rocprofiler_configure symbol during registration. This is the recommended way to load a custom tool that is not already in the process’s link map.

Warning

The current parser splits on : but drops the token after the last : separator. Until this is fixed, prefer a single path, or append a trailing : (for example /path/libA.so:/path/libB.so:) to ensure every entry is loaded.

LD_PRELOAD

(unset)

Standard dynamic-loader mechanism. If your tool library is listed in LD_PRELOAD, it is loaded before any runtime, and its rocprofiler_configure symbol is discovered automatically (without needing ROCP_TOOL_LIBRARIES). Use this when the tool must intercept symbols or perform work before the runtime initializes.

Note

ROCP_TOOL_LIBRARIES failure modes differ:

  • If an entry cannot be dlopened (for example, the file does not exist or has unresolved dependencies), the SDK calls ROCP_FATAL and the process terminates.

  • If an entry is loaded but does not export rocprofiler_configure, a warning is logged and that library is simply not registered as a tool; the process continues.

Logging and diagnostics#

These variables are the first thing to reach for when debugging a custom tool that is not being loaded, not being initialized, or not receiving callbacks.

Variable

Default

Description

ROCPROFILER_LOG_LEVEL

warning

Severity threshold for SDK log output. Accepted values:

  • Named levels: trace, info, warning, error, fatal.

  • Integer levels 0–4 mapping to the named levels above (0 = fatal, 4 = trace).

Log messages are emitted to stderr.

Queue interception behavior#

This variable controls how ROCprofiler-SDK intercepts HSA queue operations. It is an advanced knob: most tools do not need to set it, and the default is chosen automatically based on the services your tool enables.

Variable

Default

Description

ROCPROFILER_QUEUE_INTERPOSITION

(auto)

Boolean (true/false). Selects between inline queue interposition (a shadow write-pointer that intercepts queue operations without the legacy intercept queue) and the legacy hsa_amd_queue_intercept_create path.

When unset, the SDK chooses automatically: inline interposition is enabled only when no registered context requires dispatch counter collection, thread trace (ATT), or PC sampling; otherwise the legacy path is used.

If you set this to true while a context that requires the legacy path (counter collection, ATT, or PC sampling) is registered, the SDK logs a warning and falls back to the legacy path anyway.

Beta-feature opt-in#

Tools that use beta services must enable them explicitly. Without these variables, the corresponding configuration calls return an error.

Variable

Default

Description

ROCPROFILER_PC_SAMPLING_BETA_ENABLED

false

Enables the PC sampling service. Required to call rocprofiler_configure_pc_sampling_service from a custom tool.

ROCPROFILER_SPM_BETA_ENABLED

false

Enables Streaming Performance Monitor (SPM) counter collection.

Agent visibility#

These standard ROCm runtime variables influence which agents the SDK exposes to your tool through the agent-information API. They are not owned by ROCprofiler-SDK, but custom tools that enumerate agents need to be aware of them.

Variable

Default

Description

ROCR_VISIBLE_DEVICES

(all)

Standard ROCm runtime selector. Restricts the set of agents the runtime — and therefore the SDK — sees. Affects iteration through rocprofiler_query_available_agents.

HIP_VISIBLE_DEVICES / CUDA_VISIBLE_DEVICES / GPU_DEVICE_ORDINAL

(all)

HIP-level device selectors. These affect which agents HIP exposes but do not directly hide agents from the SDK; tools that correlate HIP device ordinals with SDK agent IDs must account for the mapping.

Minimal worked example#

Launching an application with a custom tool libmy_tool.so and verbose SDK logging:

export ROCP_TOOL_LIBRARIES=/path/to/libmy_tool.so
export ROCPROFILER_LOG_LEVEL=info
./my_application

Equivalent invocation using LD_PRELOAD (useful when the tool must also intercept symbols from the target):

LD_PRELOAD=/path/to/libmy_tool.so \
    ROCPROFILER_LOG_LEVEL=info \
    ./my_application

See also#

Contents