Tracing NVTX Events with NVIDIA Nsight Systems

The NVIDIA Tools Extension Library (NVTX) is a powerful mechanism that allows users to manually instrument their application. NVIDIA Nsight Systems can then collect the information and present it on the timeline.

Nsight Systems supports version 3.0 of the NVTX specification.

The following features are supported:

To learn more about specific features of NVTX, please refer to the NVTX header file: nvToolsExt.h or the NVTX Documentation.

To use NVTX in your application, follow these steps:

  1. Add #include "nvToolsExt.h" in your source code. This header file is located in the Target-x86_64/nvtx/include/nvtx3 directory on the host.

  2. Add the following compiler flag: -ldl

  3. Add calls to the NVTX API functions. For example, try adding nvtxRangePush("main") in the beginning of the main() function, and nvtxRangePop() just before the return statement in the end.

    • For convenience in C++ code, consider adding a wrapper that implements RAII (resource acquisition is initialization) pattern, which would guarantee that every range gets closed.
  4. In the project settings, select the Collect NVTX trace checkbox.

Typically calls to NVTX functions can be left in the source code even if the application is not being built for profiling purposes, since the overhead is very low when the profiler is not attached.

NVTX is not intended to annotate very small pieces of code that are being called very frequently. A good rule of thumb to use: if code being annotated usually takes less than 1 microsecond to execute, adding an NVTX range around this code should be done carefully.

Note: range annotations should be matched carefully. If many ranges are opened but not closed, Nsight Systems has no meaningful way to visualize it. A rule of thumb is to not have more than a couple dozen ranges open at any point in time. Nsight Systems does not support reports with many unclosed ranges.


NVIDIA® GameWorks™ Documentation Rev. 1.0.220830 ©2014-2022. NVIDIA Corporation and affiliates. All Rights Reserved.