Introduction to ROCTracer

Introduction to ROCTracer#

ROCTracer consists of the ROCTracer and ROC-TX libraries, which provide APIs to help you trace an application in the runtime. The runtime-independent API enables tracing runtime calls and asynchronous activities such as GPU kernel dispatches and memory moves to profile the application and hardware performance.

  • ROCTracer library

    The ROCTracer library provides runtime-independent APIs for tracing runtime calls and asynchronous activities such as GPU kernel dispatches and memory moves. The tracing includes callback APIs for runtime API tracing and activity APIs for asynchronous activity records logging. You can utilize these APIs to develop a tracing tool or to implement tracing in the application. Refer to ROCTracer library specification for details.

  • ROC-TX library

    In certain situations, such as debugging performance issues in large-scale GPU programs, API-level tracing may be too fine-grained to provide a big picture of the program execution. In such cases, it is helpful to define specific tasks to be traced.

    To specify the tasks for tracing, enclose the respective source code with API calls from the ROC-TX library. This process is also known as instrumentation. As the scope of code for instrumentation is defined using the enclosing API calls, it is called a range. A range is a programmer-defined task that has a well-defined start and end code scope. You can also fine grain the scope specified within a range using further nested ranges. Refer to ROC-TX library specification for additional details.

Using the rocTracer API#

To use the rocTracer API, link the application with ROCTracer using the API header and dynamic library as shown below:

  • API header: /opt/rocm-{version}/include/roctracer/roctracer.h

  • Dynamic library (.so): /opt/rocm-{version}/lib/libroctracer64.so.<version major>

Using the rocTX API#

To use the rocTX API you need the API header and to link your application with roctx .so library:

  • API header: /opt/rocm-{version}/roctracer/include/roctx.h

  • Dynamic library (.so): /opt/rocm-{version}/lib/libroctx64.so.<version major>