
This file documents changes and updates to the Nsight Systems export schema.
For the purpose of this document, changes will be described using SQLite
terminology (i.e. "Table", "Column", "Row", etc.) but apply to all major
export formats (SQLite, HD5, Arrow, Parquet).

The schema version is represented as three numbers, such as "3.2.1". The
three numbers represent "major", "minor", and "micro" changes in the version.
Different changes, with different scopes, cause different version numbers
to be changed. Ideally they follow this pattern:

  MAJOR:  Breaking changes that affect a significant percentage of queries
  MINOR:  Localized breaking changes that are unlikely to affect most queries
  MICRO:  Non-breaking additions (new tables, new columns to existing tables)

Although there is an attempt to follow this convention, historically the
versions haven't always followed this exact pattern. Additionally, sometimes
changes are made to the help-text found within the schema. These are often
to clarify the description or fix typos. Sometimes these changes result in
a change to the schema version without an actual change to the schema itself.

The version of a particular export file can be found with this query:
    SELECT name, value
      FROM META_DATA_EXPORT
      WHERE name LIKE 'EXPORT_SCHEMA_VERSION%';

A short description of each change is given below, newer changes at the time.
Changes marked with a "*" are "breaking," in that they might require
modification to scripts or notebooks that use the exports for data analysis.
Note that column additions, INCLUDING ADDITIONS THAT ARE NOT AT THE END OF
THE TABLE DEFINITION, are NOT considered breaking, even though they might
break "SELECT *" type queries that reference results by column index. That's
considered poor practice and queries should not be written that way.

===========================================================================
3.17.2
  Column added: CUPTI_ACTIVITY_KIND_MEMCPY.copyCount

3.17.1
  Row added: META_DATA_CAPTURE
    NETWORK_PROFILING_OPTIONS:PERF_NIC_DEVICE

3.17.0
  Column added: CUPTI_ACTIVITY_KIND_CUDA_EVENT.eventSyncId
  Column added: CUPTI_ACTIVITY_KIND_SYNCHRONIZATION.eventSyncId
  Column renamed: The original CUPTI_ACTIVITY_KIND_SYNCHRONIZATION.syncType is
    renamed to CUPTI_ACTIVITY_KIND_SYNCHRONIZATION.deprecatedSyncType
  Column added: A new CUPTI_ACTIVITY_KIND_SYNCHRONIZATION.syncType column

3.16.4
  Table added: TARGET_INFO_CUDA_DEVICE

3.16.3
  Table added: ENUM_NET_IB_CONGESTION_EVENT_TYPE
  Behavior change: NET_IB_SWITCH_CONGESTION_EVENT.congestionType now has
    valid data

3.16.2
  Table added: NVTX_SCOPES

3.16.1
  Column added: CUDA_UM_CPU_PAGE_FAULT_EVENTS.sourceFile
  Column added: CUDA_UM_CPU_PAGE_FAULT_EVENTS.sourceLine

3.16.0
  *Column deleted: CUPTI_ACTIVITY_KIND_WARP_PHASE_TRACE.phase1Timestamp
  *Column deleted: CUPTI_ACTIVITY_KIND_WARP_PHASE_TRACE.phase2Timestamp

3.15.0
  Behavior change: GPU Metrics events are exported to GPU_METRICS table only
  (previously were duplicated to GENERIC_EVENTS/GENERIC_EVENT_DATA)
  Table added: SOC_METRICS
  Table added: TARGET_INFO_SOC_METRICS

3.14.0 (no version change)
  Table added: CUPTI_ACTIVITY_KIND_BLOCK_TRACE
  Table added: CUPTI_ACTIVITY_KIND_BLOCK_PHASE_TRACE
  Table added: CUPTI_ACTIVITY_KIND_WARP_TRACE
  Table added: CUPTI_ACTIVITY_KIND_WARP_PHASE_TRACE

3.14.0
 *Column deleted: ANALYSIS_FILE.content
  Column added: ANALYSIS_FILE.contentId

  Changed "content" column from a string value to a reference to the
     StringIds table.

3.13.5
  Table added: NET_IB_SWITCH_METRIC

3.13.4
  Column added: CUDA_GPU_MEMORY_USAGE_EVENTS.streamId

3.13.3 (no version change)
  Behavior change: TEXT and BLOB values truncated to 1GB; not technically
    a breaking change, as the SQLite export failed completely if this
    limit was exceeded

3.13.3
  Column added: CUPTI_ACTIVITY_KIND_OPENACC_DATA.correlationId
  Column added: CUPTI_ACTIVITY_KIND_OPENACC_LAUNCH.correlationId
  Column added: CUPTI_ACTIVITY_KIND_OPENACC_OTHER.correlationId

3.13.2
  Table added: NVTX_PAYLOAD_SCHEMAS
  Table added: NVTX_PAYLOAD_SCHEMA_ENTRIES
  Table added: NVTX_PAYLOAD_ENUMS
  Table added: NVTX_PAYLOAD_ENUM_ENTRIES
  Column added: NVTX_EVENTS.binaryData

3.13.1 (no version change)
  Behavior change: TRACE_PROCESS_EVENT_NVMEDIA.start/end columns
    can be correctly time filtered

3.13.1 (no version change)
  Table added: TEGRA_INTERNAL_API_CALLS
  ENUM added: ENUM_NSYS_EVENT_CLASS:TRACE_PROCESS_EVENT_TEGRA_INTERNAL
  ENUM added: ENUM_NSYS_EVENT_CLASS:TRACE_PROCESS_EVENT_TEGRA_INTERNAL_START
  ENUM added: ENUM_NSYS_EVENT_CLASS:TRACE_PROCESS_EVENT_TEGRA_INTERNAL_FINISH

3.13.1
  Table added: ENUM_SCHEDULING_THREAD_BLOCK
  Column added: SCHED_EVENTS.threadState
  Column added: SCHED_EVENTS.threadBlock

3.13.0
  Column added: GENERIC_EVENT.genericEventId
 *Column change: GENERIC_EVENT.timestamp added NOT NULL
  Column added: GENERIC_EVENT.globalTid
  Table added: GENERIC_EVENT_DATA
  Table added: GENERIC_EVENT_TYPES
  Table added: GENERIC_EVENT_TYPE_FIELDS
  Table added: GENERIC_EVENT_TYPE_FIELD_MAP
 *Behavior change: GENERIC_EVENT_SOURCES.data (JSON data) not exported unless
    the --includeJson flag is given to the "nsys export" command
  Column added: GENERIC_EVENT_SOURCES.nameId
  Column added: GENERIC_EVENT_SOURCES.timeSourceId
  Column added: GENERIC_EVENT_SOURCES.sourceGroupId
  Column added: GENERIC_EVENT_SOURCES.hyperType
  Column added: GENERIC_EVENT_SOURCES.hyperVersion
  Column added: GENERIC_EVENT_SOURCES.hyperStructPrefix
  Column added: GENERIC_EVENT_SOURCES.hyperMacroPrefix
  Column added: GENERIC_EVENT_SOURCES.hyperFilterFlags
  Column added: GENERIC_EVENT_SOURCES.HyperDomain
  Table added: ENUM_NSYS_GENERIC_EVENT_SOURCE
  Table added: ENUM_NSYS_GENERIC_EVENT_GROUP
  Table added: ENUM_NSYS_GENERIC_EVENT_FIELD_TYPE
  Table added: ENUM_NSYS_GENERIC_EVENT_FIELD_ETW_PROPERTY
  Table added: ENUM_NSYS_GENERIC_EVENT_FIELD_ETW_TYPE
  Table added: ENUM_NSYS_GENERIC_EVENT_FIELD_ETW_FLAGS
 *Column change: GPU_METRICS.timestamp added NOT NULL
  Column added: GPU_METRICS.rawTimestamp
  Column added: ETW_EVENTS.rawTimestamp
 *Column deleted: ETW_EVENTS.processId
 *Column deleted: ETW_EVENTS.treadId
  Column added: ETW_EVENTS.globalTid
 *Column deleted: ETW_EVENTS.providerId
 *Column deleted: ETW_EVENTS.taskId
 *Column deleted: ETW_EVENTS.eventId
 *Column deleted: ETW_EVENTS.version
  Column added: ETW_EVENTS.typeId

3.12.1
  Table added: SYSCALL
  ENUM added: ENUM_NSYS_EVENT_CLASS:TRACE_PROCESS_EVENT_SYSCALL

3.12.0 (no version change)
 *Behavior change: NVTX_EVENTS.jsonText format change

3.12.0
 *Table renamed: PERF_EVENT_CPU_RAW_EVENT
              -> PERF_EVENT_SOC_OR_CPU_RAW_EVENT
 *Table renamed: PERF_EVENT_CPU_METRIC_EVENT
              -> PERF_EVENT_SOC_OR_CPU_METRIC_EVENT

3.11.7 (no version change)
 *Row value renamed: META_DATA_EXPORT.EXPORT_PARAM_OUTUPT_FILE
                  -> META_DATA_EXPORT.EXPORT_PARAM_OUTPUT_FILE
 *Row value renamed: META_DATA_EXPORT.EXPORT_PARAM_OUTUPT_PATH
                  -> META_DATA_EXPORT.EXPORT_PARAM_OUTPUT_PATH
 *Row value renamed: META_DATA_EXPORT.EXPORT_PARAM_OUTUPT_PATH_ABS
                  -> META_DATA_EXPORT.EXPORT_PARAM_OUTPUT_PATH_ABS

3.11.7
 *Table removed: GPU_MEMORY_BUDGET_EVENTS
 *Table removed: GPU_MEMORY_USAGE_EVENTS
 *Table removed: DEMOTED_BYTES_EVENTS
 *Table removed: TOTAL_BYTES_RESIDENT_IN_SEGMENT_EVENTS
 *Table removed: ETW_EVENTS_DEPRECATED_TABLE

3.11.6
  Table added: TARGET_INFO_COMPONENT

3.11.5
  Column added: NVVIDEO_ENCODER_API.apiId
  Column added: NVVIDEO_DECODER_API.apiId
  Column added: GPU_VIDEO_ENGINE_WORKLOAD.apiId
  Column added: GPU_VIDEO_ENGINE_WORKLOAD.codecId

3.11.4
 *Behavior change: GENERIC_EVENT.data (JSON data) not exported unless
    the --includeJson flag is given to the "nsys export" command

3.11.3
  Column added: NET_NIC_METRIC.portId
  Column added: NET_IB_SWITCH_METRIC.portId

3.11.2
  No schema changes

3.11.1
  Table added: NET_IB_DEVICE_INFO
  Table added: NET_IB_DEVICE_PORT_INFO
  Table added: NET_IB_DEVICE_TYPE_MAP
  Table added: ENUM_NET_IB_DEVICE_TYPE

3.11.0
  Table added: DX12_MEMORY_OPERATION
  Table added: MEMORY_TRANSFER_EVENTS
  Table added: META_DATA_CAPTURE
  Table added: TEGRA_INTERNAL_API_CALLS
  Table added: TRACE_PROCESS_EVENT_NVMEDIA
  Table added: UCP_WORKERS
  Table added: UNCORE_PMU_EVENTS
  Table added: UNCORE_PMU_EVENT_VALUES

3.10.0 (no version change)
  Table added: CUPTI_ACTIVITY_KIND_CUDA_EVENT
  Table added: CUPTI_ACTIVITY_KIND_GRAPH_TRACE

3.10.0
  Column added: GPU_VIDEO_ENGINE_WORKLOAD.contextId
 *ENUM changed: ENUM_VIDEO_ENGINE_CODEC.AVD
             -> ENUM_VIDEO_ENGINE_CODEC.AV1

3.9.0 (no version change)
 *Behavior change: CUPTI_ACTIVITY_KIND_RUNTIME.callchainId
    Fixed off-by-one error

3.9.0 (no version change)
 *Behavior change: GPU_VIDEO_ENGINE_WORKLOAD.engineType
    Export correct value
 *Behavior change: GPU_VIDEO_ENGINE_WORKLOAD.engineId
    Export correct value

3.9.0
 *Row removed: META_DATA_CAPTURE
    NETWORK_PROFILING_OPTIONS:CONGESTION_EVENTS_DATA_DIR
  Row added: META_DATA_CAPTURE
    NETWORK_PROFILING_OPTIONS:CONGESTION_PERCENT
  Row added: META_DATA_CAPTURE
    NETWORK_PROFILING_OPTIONS:CONGESTION_THRESHOLD_HIGH
  Row added: META_DATA_CAPTURE
    NETWORK_PROFILING_OPTIONS:CONGESTION_NIC_DEVICE

3.8.0 (out of order)
 *Row removed: META_DATA_CAPTURE
    *:NETWORK_PROFILING_OPTIONS:SHOULD_COLLECT_NIC_METRICS
 *Row removed: META_DATA_CAPTURE
    *:NETWORK_PROFILING_OPTIONS:SWITCH_GUIDS_FOR_PERF_METRICS
 *Row removed: META_DATA_CAPTURE
    *:NETWORK_PROFILING_OPTIONS:SWITCH_GUIDS_FOR_CONGESTION_EVENTS
 *Row removed: META_DATA_CAPTURE
    *:NETWORK_PROFILING_OPTIONS:CONGESTION_EVENTS_DATA_DIR

3.8.5
  Table added: ANALYSIS_FILE

3.8.4 (no version change)
  Table added: DIAGNOSTIC_EVENT

3.8.4
  Table added: CUPTI_ACTIVITY_KIND_GRAPH_TRACE
  Table added: CUDA_GRAPH_EVENTS

3.7.4
  Table added: PERF_EVENT_CPU_METRIC_EVENT

3.7.3
  Table added: GPU_VIDEO_ENGINE_WORKLOAD
  Table added: GPU_VIDEO_ENGINE_MISSING
  Table added: ENUM_VIDEO_ENGINE_TYPE
  Table added: ENUM_VIDEO_ENGINE_CODEC

-- approx Dec 2023 --
