# SQLite Export Schema Reference

This section describes in-depth exported data types. Since the tool is still BETA, please note, that the format may likely change in the future. Also, not every exported field may have been documented at this time.

Current logic behind the chosen layout is that each data type gets it’s own table in the exported database. Since usage patterns for exported data may vary greatly and no default use cases has been established yet, no indexes or extra constraints are created. Instead, refer to the Examples section for list of common recipes.

Due to current limitations, all fields are declared as NOT NULL, even where actual value may be missing, instead default value for that field is exported. This might change in future versions.

## CUDA

### Runtime API

Table name | CUPTI_ACTIVITY_KIND_RUNTIME
--- | ---
Column Name | Column Type | Column Description
start | INT NOT NULL | Event start timestamp in nanoseconds.
end | INT NOT NULL | Event end timestamp in nanoseconds.
globalTid | INT NOT NULL | Serialized GlobalId.
correlationId | INT NOT NULL | Use this value to find events in `CUPTI_ACTIVITY_KIND_KERNEL`, `CUPTI_ACTIVITY_KIND_MEMSET`, `CUPTI_ACTIVITY_KIND_MEMCPY`, tables that this function call has triggered. For an example refer to Transfer CUDA kernel names onto API ranges.
nameId | INT NOT NULL | StringId of function name.
returnValue | INT NOT NULL | Return value of function call.

### Kernel events

Table name | CUPTI_ACTIVITY_KIND_KERNEL
--- | ---
Column Name | Column Type | Column Description
start | INT NOT NULL | Event start timestamp in nanoseconds.
end | INT NOT NULL | Event end timestamp in nanoseconds.
deviceId | INT NOT NULL | The ID of the device where the kernel is executing.
contextId | INT NOT NULL | The ID of the context where the kernel is executing.
streamId | INT NOT NULL | The ID of the stream where the kernel is executing.
correlationId | INT NOT NULL | Use this value to find events in `CUPTI_ACTIVITY_KIND_RUNTIME` table that triggered execution of given kernel. For an example refer to Transfer CUDA kernel names onto API ranges.
globalPid | INT NOT NULL | Serialized GlobalId.
demangledName | INT NOT NULL | StringId of kernel name.
shortName | INT NOT NULL | StringId of short (without arguments) function name.
launchType | INT NOT NULL | The indicates if the kernel was executed via a regular launch or via a single/multi device cooperative launch.
cacheConfig | INT NOT NULL | The cache configuration used for the kernel. The value is one of the CUfunc_cache enumeration values from cuda.h.
registersPerThread | INT NOT NULL | The number of registers required for each thread executing the kernel.
gridX | INT NOT NULL | The X-dimension grid size for the kernel.
gridY | INT NOT NULL | The Y-dimension grid size for the kernel.
gridZ | INT NOT NULL | The Z-dimension grid size for the kernel.
blockX | INT NOT NULL | The X-dimension block size for the kernel.
blockY | INT NOT NULL | The Y-dimension block size for the kernel.
blockZ | INT NOT NULL | The Z-dimension block size for the kernel.
staticSharedMemory | INT NOT NULL | The static shared memory allocated for the kernel, in bytes.
dynamicSharedMemory | INT NOT NULL | The dynamic shared memory reserved for the kernel, in bytes.
localMemoryPerThread | INT NOT NULL | The amount of local memory reserved for each thread, in bytes.
localMemoryTotal | INT NOT NULL | The total amount of local memory reserved for the kernel, in bytes.
gridId | INT NOT NULL | The grid ID of the kernel. Each kernel is assigned a unique grid ID at runtime.
sharedMemoryExecuted | INT NOT NULL | Shared memory size set by the driver.

### Memset Events

Table name | CUPTI_ACTIVITY_KIND_MEMSET
--- | ---
Column Name | Column Type | Column Description
start | INT NOT NULL | Event start timestamp in nanoseconds.
end | INT NOT NULL | Event end timestamp in nanoseconds.
deviceId | INT NOT NULL | The ID of the device where the memory set is occurring.
contextId | INT NOT NULL | The ID of the context where the memory set is occurring.
streamId | INT NOT NULL | The ID of the stream where the memory set is occurring.
correlationId | INT NOT NULL | Use this value to find events in `CUPTI_ACTIVITY_KIND_RUNTIME` table that triggered execution of given memory operation.
globalPid | INT NOT NULL | Serialized GlobalId.
value | INT NOT NULL | The value being assigned to memory by the memory set.
bytes | INT NOT NULL | The number of bytes being set by the memory set.

### Memcpy Events

Table name | CUPTI_ACTIVITY_KIND_MEMCPY
--- | ---
Column Name | Column Type | Column Description
start | INT NOT NULL | Event start timestamp in nanoseconds.
end | INT NOT NULL | Event end timestamp in nanoseconds.
deviceId | INT NOT NULL | The ID of the device where the memory copy is occurring.
contextId | INT NOT NULL | The ID of the context where the memory copy is occurring.
streamId | INT NOT NULL | The ID of the stream where the memory copy is occurring.
correlationId | INT NOT NULL | Use this value to find events in `CUPTI_ACTIVITY_KIND_RUNTIME` table that triggered execution of given memory operation.
globalPid | INT NOT NULL | Serialized GlobalId.
copyKind | INT NOT NULL | The kind of the memory copy.
srcKind | INT NOT NULL | The source memory kind read by the memory copy.
bytes | INT NOT NULL | The number of bytes transferred by the memory copy.

## NVTX

All NVTX events are collected in a single table. Differentiate between marks, start/end and push/pop ranges by the eventType column.

Table name | NVTX_EVENTS
--- | ---
Column Name | Column Type | Column Description
start | INT NOT NULL | Event start timestamp in nanoseconds.
end | INT NOT NULL | Event end timestamp in nanoseconds.

eventType

INT NOT NULL

EventType enum, possible values:

- 34 - NvtxMark
- 39 - NvtxThread
- 59 - NvtxPushPopRange
- 60 - NvtxStartEndRange

rangeId | INT NOT NULL | For start/end ranges only - unique id provided by NVTX library.
text | TEXT NOT NULL | User supplied text message for a given event.
category | INT NOT NULL | User-controlled ID that can be used to group events.
color | INT NOT NULL | Encoded ARGB color value.
globalTid | INT NOT NULL | Serialized GlobalId.
domainId | INT NOT NULL | User-controlled ID that can be used to group events.

## OpenGL

Table name | OPENGL_API, OPENGL_WORKLOAD
--- | ---
Column Name | Column Type | Column Description
start | INT NOT NULL | Event start timestamp in nanoseconds.
end | INT NOT NULL | Event end timestamp in nanoseconds.
globalTid | INT NOT NULL | Serialized GlobalId.
nameId | INT NOT NULL | StringId of function name.
returnValue | INT NOT NULL | Return value of function call.

## OS Runtime Libraries Trace

OS runtime libraries can be traced to gather information about low-level userspace APIs. This traces the system call wrappers and thread synchronization interfaces exposed by the C runtime and POSIX Threads (pthread) libraries. This does not perform a complete runtime library API trace, but instead focuses on the functions that can take a long time to execute, or could potentially cause your thread be unscheduled from the CPU while waiting for an event to complete.

OSRT events may have callchains attached to them, depending on selected profiling settings. In such cases, one can use callchainId column to select relevant callchains from OSRT_CALLCHAINS table, refer to OSRT Callchains for an example.

Table name | OSRT_API
--- | ---
Column Name | Column Type | Column Description
start | INT NOT NULL | Event start timestamp in nanoseconds.
end | INT NOT NULL | Event end timestamp in nanoseconds.
globalTid | INT NOT NULL | Serialized GlobalId.
nameId | INT NOT NULL | StringId of function name.
returnValue | INT NOT NULL | Return value of function call.
callchainId | INT NOT NULL | De facto FOREIGN KEY to OSRT_CALLCHAINS.id. The value of 0 is used instead of NULL.

### Callchains

Table name | OSRT_CALLCHAINS
--- | ---
Column Name | Column Type | Column Description
id | INT NOT NULL | Part of PRIMARY KEY (id, stackDepth). Maps to OSRT_API.callchainId.
stackDepth | INT NOT NULL | Zero-base index of given function in call stack.
symbol | INT NOT NULL | StringId of function name.
module | INT NOT NULL | StringId of module name.

## Profiler Overhead

Table name | PROFILER_OVERHEAD
--- | ---
Column Name | Column Type | Column Description
start | INT NOT NULL | Event start timestamp in nanoseconds.
end | INT NOT NULL | Event end timestamp in nanoseconds.
globalTid | INT NOT NULL | Serialized GlobalId.
nameId | INT NOT NULL | StringId of function name.
returnValue | INT NOT NULL | Return value of function call.

## Secondary tables

### String Ids

NVIDIA Nsight Systems stores strings from events in a global storage, each unique string has a corresponding integer id. The StringIds table is created from that storage.

Table name | StringIds
--- | ---
Column Name | Column Type | Column Description
id | INTEGER PRIMARY KEY | Integer key of a string.
value | TEXT NOT NULL | Text content of a string.

### Thread Names

Table name | ThreadNames
--- | ---
Column Name | Column Type | Column Description
nameId | INTEGER PRIMARY KEY | StringId of thread name.
globalTid | INT NOT NULL | Serialized GlobalId.

### Enums

Protobuf enumeration types are exported as tables. Here’s an example structure for UnwindMethodType enumeration:

Table name | UnwindMethodType
--- | ---
Column Name | Column Type | Column Description
number | INTEGER PRIMARY KEY | Integer value of an enum constant.
name | TEXT NOT NULL | Text name of an enum constant.

## Extra types

### CUDA CopyKind enum

    enum CUDA_MEMCPY_KIND
    {
        CUDA_MEMCPY_KIND_UNKNOWN,
        CUDA_MEMCPY_KIND_HTOD,
        CUDA_MEMCPY_KIND_DTOH,
        CUDA_MEMCPY_KIND_HTOA,
        CUDA_MEMCPY_KIND_ATOH,
        CUDA_MEMCPY_KIND_ATOA,
        CUDA_MEMCPY_KIND_ATOD,
        CUDA_MEMCPY_KIND_DTOA,
        CUDA_MEMCPY_KIND_DTOD,
        CUDA_MEMCPY_KIND_HTOH,
        CUDA_MEMCPY_KIND_PTOP,
        CUDA_MEMCPY_KIND_UVM_HTOD,
        CUDA_MEMCPY_KIND_UVM_DTOH,
        CUDA_MEMCPY_KIND_UVM_DTOD,
    };

### Serialized process and thread identifiers

NVIDIA Nsight Systems stores identifiers where events originated in serialized form. For events that have `globalTid` or `globalPid` fields exported, use the following code to extract numeric TID and PID:

    SELECT globalTid / 0x1000000 % 0x1000000 AS PID, globalTid % 0x1000000 AS TID FROM TABLE_NAME;

NOTE: `globalTid` field includes both TID and PID values, while `globalPid` only the PID value.