TheRock/rocm-systems/projects/rocprofiler-sdk/source/docs/api-reference/tool_library_environment.rst

.. meta::
    :description: Environment variables relevant to authors of custom ROCprofiler-SDK tools
    :keywords: ROCprofiler-SDK, custom tool, environment variables, ROCP_TOOL_LIBRARIES, logging

.. _tool-library-environment:

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 :ref:`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 ``dlopen``\ed 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.

.. list-table::
    :header-rows: 1
    :widths: 25 15 60

    * - Variable
      - Default
      - Description
    * - ``ROCP_TOOL_LIBRARIES``
      - (unset)
      - Colon-separated list of absolute paths to shared libraries that export
        ``rocprofiler_configure``. ROCprofiler-SDK ``dlopen``\s 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 ``dlopen``\ed (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.

.. list-table::
    :header-rows: 1
    :widths: 30 15 55

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

.. list-table::
    :header-rows: 1
    :widths: 30 15 55

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

.. list-table::
    :header-rows: 1
    :widths: 35 15 50

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

.. list-table::
    :header-rows: 1
    :widths: 28 15 57

    * - 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:

.. code-block:: bash

    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):

.. code-block:: bash

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

See also
--------

- :ref:`tool-library` — overview of the custom tool API and ``rocprofiler_configure``.
- :ref:`process_attachment_implementation` — environment considerations when attaching to an already-running process.