The NVIDIA Tools Extension SDK (NVTX) is a C-based Application Programming Interface (API) for annotating an application. Emitted NVTX annotations are captured and visualized in NVIDIA Nsight on the timeline and custom report pages. In some cases the C-based API might not be applicable or already existing logging infrastructures are difficult to output annotations through the NVTX API.
To address that, NVIDIA Nsight introduces NVTXT, a text version of the Tools Extension SDK. It is based on human-readable *.nvtxt files that can be added to an analysis report to annotate a trace capture. It supports the same marker and ranges events (Markers, Push/Pop Ranges, Start/End Ranges), and the annotations are visualized the same way on the timeline as NVTX annotations. It is possible to use NVTX and NVTXT at the same time.
An NVTXT file is a plain text file with an .nvtxt file extension and can be opened and read by any text editor. Each line contains either one NVTXT instruction or a comment.
There are 3 kinds of NVTXT instructions available:
A comment line begins with a pound sign (#). All characters on that line will be treated as comments and will consequently be ignored by the parser.
Variables allow referencing values by name in subsequent instructions. Variables are valid from the point they get defined first until the end of the NVTXT file. Their value remains constant from the initial assignment up to either, the end of the file or the next assignment to the same variable.
NVTXT supports 2 kinds of variables: Strings and Integers.
In order to be valid, a String must have one of the following two characteristics:
In order to be valid, an Integer must have one of the following two characteristics:
Int64. 0x or 0X, followed by digits of letters between A and F (or a and f) to be treated as an hexadecimal number.As an example, all of the following variables are considered to be valid:
A variable assignment takes this form:
Variable[white-space]=[white-space]value
The left-operand of the assignment is the variable name and it must consist solely of letters, digits, and the '_' (underscore) and cannot begin with a digit.
A variable can be expanded anywhere (except between single and double quotes) to retrieve its value. The variable expansion is done during the lexing stage.
To expand a variable, place a dollar sign ($) before a previously assigned variable name.
Note that trying to expand an undefined variable will result in a lexing error.
NVTXT contains a finite set of commands, with each one containing a predefined list of arguments. Some arguments can be made static, which means that their value will not be read from the command call, but instead from a variable with the same name.
A command definition always begins with the at sign (@) prepended to a valid command name, and is followed by a series of valid argument names, delimited by a comma (,). For example:
@CommandName,[whitespace]Property1,[whitespace]Property2,[whitespace]Property3
A command definition is valid for all subsequent calls of this command. A command definition can be redefined multiple times in a single NVTXT file.
For example, the RangeStartEnd command's default format is as follows:
@RangeStartEnd, Start, End, TimeBase, ProcessId, ThreadId, CategoryId, Color, Message, Payload
The following defines all available commands supported in NVTXT. Optional parameters are denoted in italics.
<Time>, with <Color> as color, <Message> as label and <Payload> as payload.
Marker, Time, TimeBase, ProcessId, ThreadId, CategoryId, Color, Message, Payload
<Time>, with <Color> as color, <Message> as label and <Payload> as payload. Calls to RangePush need to be paired with corresponding calls to RangePop.
RangePush, Time, TimeBase, ProcessId, ThreadId, CategoryId, Color, Message, Payload
<Time> and starting with the corresponding RangePush command.
RangePop, Time, TimeBase, ProcessId, ThreadId
<Start> and <End>, with <Color> as color, <Message> as label and <Payload> as payload. Multiple Start/End ranges can overlap each other.
RangeStartEnd, Start, End, TimeBase, ProcessId, ThreadId, CategoryId, Color, Message, Payload
<Name> to the category with ID <CategoryId>.
NameCategory, CategoryId, Name
AddChildCategory, ParentCategoryId, CategoryId
<ThreadId> thread on <ProcessId> process.
NameOsThread, ProcessId, ThreadId, Name
<ProcessId> process.
NameProcess, ProcessId, Name
SetFileDisplayName, Name
The arguments to the commands are defined in the following list. The type of the argument is specified in square brackets. Multiple brackets denote distinct options to define the argument value.
[Integer] — A timestamp.
[String] — The time base used for the timestamps, valid values are:
Qpc — The high-resolution performance counter provided by the QueryPerformanceCounter function on Windows systems.
Rdtsc — The processor time stamp in clock cycles since the last reset. Exposed by the Visual Studio compilers through the __rdtsc intrinsic.
FileTime — The number of 100-nanosecond intervals elapsed since midnight, January 1, 1601 C.E. UTC. The File Time can be retrieved by calling the GetSystemTimeAsFileTime function or the DateTime.ToFileTime method.
[Integer] — ID of the Process.
[Integer] — ID of the Thread.
[Integer] — ID of the Category.
[Integer] — ARGB value as an integer.
[String] — Name of the color. (The list of known names is equivalent to: http://msdn.microsoft.com/en-us/library/system.drawing.color.aspx.)
[String] — ARGB value as an hexadecimal value ("0xFF004488FF").
[String] — Label of the marker/range.
[Integer] — Payload component of the range/marker.
[String] — Name of the Thread/Process/Category/File.
Below you will find an example of defining the RangeStartEnd in a custom way. The arguments where the ProcessId, ThreadId, CategoryId, Color, and TimeBase are defined as static variables. That way, those arguments do not have to be repeated for every call to this command.
@RangeStartEnd, Start, End, Message
ProcessId = 1844
ThreadId = 4880
CategoryId = 1
Color = Blue
TimeBase = Qpc
RangeStartEnd, 8236719005, 8236928073, "My Message"
A previously defined command can be issued by Command Calls. A command call always begins with a Command Name followed by a list of values corresponding to the command’s definition. Every value must have the right type and there must be the exact amount of arguments.
CommandName,[whitespace]ValueForProperty1, [whitespace]ValueForProperty2
NVTXT files that are collocated with NVIDIA Nsight's capture output get automatically loaded when a report is opened. Multiple NVTXT files can be used to annotate a report. However, each input file is handled separately; sharing of IDs, Variables, or Command Definitions across NVTXT files is not supported.
The NVTXT files can be placed at two locations in the report hierarchy to be properly loaded with a report. Any arbitrary number of NVTXT files can co-exist and be loaded at the same time. Note that the order in which they are loaded is not defined. The two locations are:
Like any file loaded alongside the report, the NVTXT file can be located in the capture folder.
For example, if the Report Directory is set to C:\temp, then the NVTXT file will be located in C:\temp\[project name]\[project name]_Capture_000\.
In the Analysis tab of the Nsight Options menu, the user can choose to enable NVTXT file loading from the session folder. Note that the default value is set to True.
By doing so, NVTXT files can also be located in the Session directory. For example, if the Report Directory is set to C:\temp, the NVTXT file will be placed in C:\temp\[project name]\.
To avoid the need to manually copy NVTXT files into the report directory structure after a capture is completed, NVIDIA Nsight provides an environment variable that points to the current session directory. This environment variable, called NSIGHT_ANALYSIS_SESSION_OUTPUT_PATH, is automatically set for the target process and remains valid during the lifetime of a session.
Note that for a remote session, every NVTXT file present in the session directory will be synchronized at the end of every capture session. Therefore, if a session contains multiple captures, old files are likely overridden. It is also the user’s responsibility to properly close any handles to the NVTXT files located in NSIGHT_ANALYSIS_SESSION_OUTPUT_PATH to make them available for file synchronization between the target and host machines.
An NVTXT file is treated like any other loadable file and will be present in the Report Summary. If it contains errors, a warning message will be shown.
For more information about the errors, you can follow the link to the Session Summary, where all of the lexing, parsing, and loading error messages will be displayed for each of the loaded NVTXT files.
NVTXT data will be displayed on the Timeline in the very same way that NVTX data is shown. However, there are two notable differences:
CategoryId (or the display name, if applicable).
NVIDIA® GameWorks™ Documentation Rev. 1.0.220830 ©2014-2022. NVIDIA Corporation and affiliates. All Rights Reserved.
