Event Attributes Structure

This structure is used to describe the attributes of an event. The layout of the structure is defined by a specific version of the tools extension library and can change between different versions of the Tools Extension library.

Attributes

Markers and ranges can use attributes to provide additional information for an event or to guide the tool's visualization of the data. Each of the attributes is optional and if left unspecified, the attributes fall back to a default value.

To specify any attribute other than the text message, the Ex variant of the function must be called.

Message

The message field can be used to specify an optional string. The caller must set both the messageType and message fields. The default value is NVTX_MESSAGE_UNKNOWN.

Code Sample: 

// VALID NVTX_MESSAGE_TYPE_ASCII
nvtxEventAttributes_t eventAttrib1 = {0}; 
eventAttrib1.version = NVTX_VERSION; 
eventAttrib1.size = NVTX_EVENT_ATTRIB_STRUCT_SIZE;
eventAttrib1.messageType = NVTX_MESSAGE_TYPE_ASCII; 
eventAttrib1.message.ascii = __FUNCTION__ ":ascii"; 
nvtxMarkEx(&eventAttrib1); 
DELAY();

// VALID NVTX_MESSAGE_TYPE_UNICODE
nvtxEventAttributes_t eventAttrib2 = {0}; 
eventAttrib2.version = NVTX_VERSION; 
eventAttrib2.size = NVTX_EVENT_ATTRIB_STRUCT_SIZE; 
eventAttrib2.messageType = NVTX_MESSAGE_TYPE_UNICODE; 
eventAttrib2.message.unicode = __FUNCTIONW__ L ":unicode \u2603 snowman"; 
nvtxMarkEx(&eventAttrib2); 
DELAY();
        

Category

A category attribute is a user-controlled ID that can be used to group events. The tool may use category IDs to improve filtering, or for grouping events. The functions nvtxNameCategoryA or nvtxNameCategoryW can be used to name a category. The default value is 0.

Code Sample:

nvtxEventAttributes_t eventAttrib = {0}; 
eventAttrib.version = NVTX_VERSION; 
eventAttrib.size = NVTX_EVENT_ATTRIB_STRUCT_SIZE; 
eventAttrib.category = 1; 
 
// specifying message to help identify this event in the tool.
eventAttrib.messageType = NVTX_MESSAGE_TYPE_ASCII; 
eventAttrib.message.ascii = __FUNCTION__; 
nvtxMarkEx(&eventAttrib); 

// Categories can be named using nvtxNameCategory{A,W}().
nvtxNameCategoryA(1, __FUNCTION__);

Color

The color attribute is used to help visually identify events in the tool. The caller must set both the colorType and color field.

Code Sample:

// valid specification of color 
nvtxEventAttributes_t eventAttrib1 = {0}; 
eventAttrib1.version = NVTX_VERSION; 
eventAttrib1.size = NVTX_EVENT_ATTRIB_STRUCT_SIZE; 
eventAttrib1.colorType = NVTX_COLOR_ARGB; 
eventAttrib1.color = COLOR_RED;
  
// specifying message to help identify this event in the tool. 
eventAttrib1.messageType = NVTX_MESSAGE_TYPE_ASCII; 
eventAttrib1.message.ascii = __FUNCTION__ ":valid color"; 
nvtxMarkEx(&eventAttrib1);  

// default color
nvtxEventAttributes_t eventAttrib2 = {0}; 
eventAttrib2.version = NVTX_VERSION; 
eventAttrib2.size = NVTX_EVENT_ATTRIB_STRUCT_SIZE;


// specifying message to help identify this event in the tool. 
eventAttrib2.messageType = NVTX_MESSAGE_TYPE_ASCII; 
eventAttrib2.message.ascii = __FUNCTION__ ":default color"; 
nvtxMarkEx(&eventAttrib2);

Payload

The payload attribute can be used to provide additional data for markers and ranges. Range events can only specify values at the beginning of a range. The caller must specify valid values for both payloadType and payload.

Code Sample:

nvtxEventAttributes_t eventAttrib = {0}; 
eventAttrib.version = NVTX_VERSION; 
eventAttrib.size = NVTX_EVENT_ATTRIB_STRUCT_SIZE; 

eventAttrib.payloadType = NVTX_PAYLOAD_TYPE_UNSIGNED_INT64; 
eventAttrib.payload.llValue = 0; 
eventAttrib.messageType = NVTX_MESSAGE_TYPE_ASCII; 
eventAttrib.message.ascii = __FUNCTION__ ":UNSIGNED_INT64 = 0"; 
nvtxMarkEx(&eventAttrib);

Structure

Initializing Attributes

The caller should always perform the following three tasks when using attributes:

• Zero the structure;

• Set the version field;

• Set the size field.

Zeroing the structure sets all the event attributes types and values to the default value. The version and size field are used by the Tools Extension implementation to handle multiple versions of the attributes structure.

Versioning

It is recommended that the caller use one of the following to methods to initialize the event attributes structure:

Version Safe

The version and size field are used by the Tools Extension implementation to handle multiple versions of the attributes structures. This example shows how to initialize the structure for forwards compatibility.

nvtxEventAttributes_t eventAttrib = {0}; 
eventAttrib.version = NVTX_VERSION; 
eventAttrib.size = NVTX_EVENT_ATTRIB_STRUCT_SIZE; 
eventAttrib.colorType = NVTX_COLOR_ARGB; 
eventAttrib.color = ::COLOR_YELLOW; 
eventAttrib.messageType = NVTX_MESSAGE_TYPE_ASCII; 
eventAttrib.message.ascii = __FUNCTION__; 
nvtxMarkEx(&eventAttrib); 

// This can be done using C99 designated initializers.
nvtxEventAttributes_t eventAttrib2 = 
{ 
     .version = NVTX_VERSION,                // version 
     .size = NVTX_EVENT_ATTRIB_STRUCT_SIZE,  // size 
     .colorType = NVTX_COLOR_ARGB,         // colorType 
     .color = COLOR_YELLOW,                  // color 
     .messageType = NVTX_MESSAGE_TYPE_ASCII, // messageType
     .message = __FUNCTION__ ":Designated Initializer" 
}; 
nvtxMarkEx(eventAttrib2);      

Version Specific

This example shows how to initialize the structure to a specific version of the library.

nvtxEventAttributes_v1 eventAttrib = {0}; 
eventAttrib.version = 1; 
eventAttrib.size = (uint16_t)(size of(nvtxEventAttributes_v1)); 
eventAttrib.colorType = NVTX_COLOR_ARGB; 
eventAttrib.color = COLOR_MAGENTA; 
eventAttrib.messageType = NVTX_MESSAGE_TYPE_ASCII; 
eventAttrib.message.ascii = __FUNCTION__; 
nvtxMarkEx(&eventAttrib); 

// This can be done using ordered initialization. 
nvtxEventAttributes_v1 eventAttrib2 = 
     { 
          1,                                          // version
         (uint16_t)(sizeof(nvtxEventAttributes_v1)), // size 
          0,                                          // category 
          NVTX_COLOR_ARGB,                            // colorType
          COLOR_CYAN,                                 // color
          NVTX_PAYLOAD_TYPE_UNSIGNED_INT64,           // payloadType 
          1,                                          // payload 
          NVTX_MESSAGE_TYPE_ASCII,                    // messageType
          __FUNCTION__ ":Ordered Initialization"// message 
     };
nvtxMarkEx(&eventAttrib2); 

If the caller uses Method 1 it is critical that the entire binary layout of the structure be configured to 0 so that all fields are initialized to the default value. The caller should either use both NVTX_VERSION and NVTX_EVENT_ATTRIB_STRUCT_SIZE (Method 1) or use explicit values and a versioned type (Method 2). Using a mix of the two methods will likely cause either source level incompatibility or binary incompatibility in the future.

API Reference

Code Example

// nvtxMark{A,W} 
nvtxMarkA(__FUNCTION__ ":nvtxMarkA"); 
nvtxMarkW(__FUNCTIONW__ L":nvtxMarkW"); 

// nvtxMarkEx 
// zero the structure 
nvtxEventAttributes_t eventAttrib = {0};

// set the version and the size information
eventAttrib.version = NVTX_VERSION; 
eventAttrib.size = NVTX_EVENT_ATTRIB_STRUCT_SIZE;
 
// configure the attributes.  0 is the default for all attributes.
eventAttrib.colorType = NVTX_COLOR_ARGB; 
eventAttrib.color = COLOR_RED; 
eventAttrib.messageType = NVTX_MESSAGE_TYPE_ASCII; 
eventAttrib.message.ascii = __FUNCTION__ ":nvtxMarkEx"; 
nvtxMarkEx(&eventAttrib);

API Reference

Code Example

// nvtxRangePush{A,W}
nvtxRangePushA(__FUNCTION__ ":nvtxRangePushA"); 
nvtxRangePop(); 
nvtxRangePushW(__FUNCTIONW__ L":nvtxRangePushW"); 
nvtxRangePop();

// nvtxRangePushEx 
// zero the structure 
nvtxEventAttributes_t eventAttrib = {0};   

// set the version and the size information 
eventAttrib.version = NVTX_VERSION; 
eventAttrib.size = NVTX_EVENT_ATTRIB_STRUCT_SIZE;  

// configure the attributes.  0 is the default for all attributes.
eventAttrib.colorType = NVTX_COLOR_ARGB; 
eventAttrib.color = COLOR_GREEN; 
eventAttrib.messageType = NVTX_MESSAGE_TYPE_ASCII; 
eventAttrib.message.ascii = __FUNCTION__ ":nvtxRangePushEx"; 
nvtxRangePushEx(&eventAttrib); 
nvtxRangePop();

API Reference

Code Example

// nvtxRangeStart{A,W}
nvtxRangeId_t id1 = nvtxRangeStartA(__FUNCTION__ ":nvtxRangeStartA"); 
nvtxRangeEnd(id1);
nvtxRangeId_t id2 = nvtxRangeStartW(__FUNCTIONW__ L":nvtxRangeStartW"); 
nvtxRangeEnd(id2); 

// zero the structure 
nvtxEventAttributes_t eventAttrib = {0};

// set the version and the size information 
eventAttrib.version = NVTX_VERSION; 
eventAttrib.size = NVTX_EVENT_ATTRIB_STRUCT_SIZE;

// configure the attributes.  0 is the default for all attributes.
eventAttrib.colorType = NVTX_COLOR_ARGB;
eventAttrib.color = COLOR_BLUE; 
eventAttrib.messageType = NVTX_MESSAGE_TYPE_ASCII; 
eventAttrib.message.ascii = __FUNCTION__ ":nvtxRangeStartEx"; 
nvtxRangeId_t id3 = nvtxRangeStartEx(&eventAttrib); 
nvtxRangeEnd(id3);

// overlapping events 
// re-use eventAttrib 
eventAttrib.message.ascii = __FUNCTION__ ":Range 1";
nvtxRangeId_t r1 = nvtxRangeStartEx(&eventAttrib); 
eventAttrib.message.ascii = __FUNCTION__ ":Range 2"; 
nvtxRangeId_t r2 = nvtxRangeStartEx(&eventAttrib); 
nvtxRangeEnd(r1); 
nvtxRangeEnd(r2);

API Reference

Code Example

nvtxNameCategory(1, "Memory Allocation"); 
nvtxNameCategory(2, "Memory Transfer"); 
nvtxNameCategory(3, "Memory Object Lifetime"); 

nvtxNameOsThread(GetCurrentThreadId(), "MAIN_THREAD");

API Reference

Code Example

CUdevice device = 0;
CUcontext context;

cuCtxCreate(&context, 0, device);

nvtxNameCuContextA(context, "Context1");
nvtxNameCuDeviceA(device, "Device0");

API Reference

Code Example

cl_context context = clCreateContextFromType(0, CL_DEVICE_TYPE_GPU, 0, 0, 0); cl_command_queue queue = clCreateCommandQueue(context, NULL, 0, NULL); nvtxNameClContextA(context, "Context1"); nvtxNameClCommandQueueA(queue, "Queue0");  

Tools Extensions Thread Rows

The per-thread data is located in the rows at \Processes\<Process>\<Thread>\Tools Extension.

The parent row includes all nvtxMark events specified on the thread. The child row, "Push/Pop Ranges," contains a nvtxRange{Push, Pop} stack for the thread. The nvtxRange{Start, End} events are not displayed per-thread, as the start and end events can occur on different threads.

Tools Extension Process Rows

The per-category events are displayed as children rows of the \Processes\<Process>\Tools Extension row.

The per-category rows \Processes\<Process>\Tools Extension\<Category> contain the nvtxMark and nvtxRange{Start, End} events associated with the category. For more information on how to associate an event with a category, and how to name a category, see the "NVTX Event Attributes" section of NVTX Library. Each category row consists of multiple stacked range graphs. The timeline view will attempt to show the minimal number of Range rows. The ranges are not displayed as a stack.

The Tools Extension Table Page

The Tools Extension Events Page provides a table view of the events. This table contains every NVTX event that was sent during the capture period. The user can use sorting and filtering to analyze the data.

Message

The message field can be used to specify an optional string. As shown below, the results can be seen both in the Tools Extension Events table, as well as on the timeline report.

Categories

Name an NVTX category with a string. Each category is defined by a unique ID, and that ID is passed into any markers, Push/Pop, or Start/End events in order to note that those events are part of a particular category. The category names show up in the report table as well as the Timeline Report alongside the category ID.

Color

The color attribute helps you to visually identify events in the tool. The results can be viewed in the Tools Extension Events and Timeline reports, shown below.

Payload

The payload field provides additional information for markers and ranges. The results are displayed in the Tools Extension Events and Timeline reports, shown below.

API Statistics

For each API domain, actively used during a time span of the target range, the range statistics table provides the total number of API calls made (API Call Count) as well as the sum of time spend to execute all those calls (API Call Duration). Both values are reported in four different ways:

• Total: Accounts for all API calls made during the time span of the target push/pop range, independent of its child ranges.

• Total %: Percentage with respect to the total value for the range, such as the overall duration of the push/pop range or the total API calls made during that duration.

• Self: Accounts for the API calls made during the times span of the target push/pop range that is not overlapping with any of the range’s children.

• Self %: Percentage with respect to the data that is not overlapping with any of the range’s child nodes.

GPU Statistics

In order to have a GPU workload event being attributed to a push/pop range, the corresponding API call that issued the GPU workload needs to be captured and this API call has to take place during the life time of the selected target range. The statistical data presented for those GPU events are the overall number of GPU workloads executed (GPU Work Count), the overall time at least one GPU workload was in flight (GPU Activity), and the overall time multiple GPU workloads were executed on the GPU (GPU Work Overlap). All performance values are reported in the four different variants as described in the previous section.

Thread Name

The user-provided thread name is used to annotate the label of the corresponding thread row. All report pages have a new column called Start Thread Name and End Thread Name that will display the name as well. This column is hidden by default, but can be enabled using the column chooser (simply right-click on a column header).

1. Capture Directory

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

2. Session Directory

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