## NVTX Trace

The NVIDIA Tools Extension Library (NVTX) is a powerful mechanism that allows users to manually instrument their application. 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:

- Domains
  - `nvtxDomainCreate()`, `nvtxDomainDestroy()`
  - `nvtxDomainRegisterString()`
- Push-pop ranges (nested ranges that start and end in the same thread).
  - `nvtxRangePush()`, `nvtxRangePushEx()`
  - `nvtxRangePop()`
  - `nvtxDomainRangePushEx()`
  - `nvtxDomainRangePop()`
- Start-end ranges (ranges that are global to the process and are not restricted to a single thread)
  - `nvtxRangeStart()`, `nvtxRangeStartEx()`
  - `nvtxRangeEnd()`
  - `nvtxDomainRangeStartEx()`
  - `nvtxDomainRangeEnd()`
- Marks
  - `nvtxMark()`, `nvtxMarkEx()`
  - `nvtxDomainMarkEx()`
- Thread names
  - `nvtxNameOsThread()`
- Categories
  - `nvtxNameCategory()`
  - `nvtxDomainNameCategory()`

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.

Copyright (c) 2012-2020, NVIDIA Corporation. All rights reserved.