Writer API#

Write pre-collected trace data through an NVTXW backend.

Regular nvtx calls annotate work as it executes. This module instead submits events and counter samples with explicit timestamps to a writer backend. The backend decides where the data is written or how it is merged.

Backend implementations and configuration are supplied by tools or other integrations. For example, NVIDIA Nsight Systems provides the nsys_writer integration; see the Nsight Systems documentation for its setup and report-specific usage.

Backend#

nvtx.writer.load_backend(path)#

Load and initialize an NVTXW backend from an explicit library path.

Parameters:

path (pathlib.Path or str) – Path to the backend shared library.

Returns:

The loaded backend.

Return type:

Backend

Raises:

  • OSError – If the library cannot be loaded.

  • WriterError – If the backend does not export nvtxwGetInterface or does not provide the requested interface version.

class nvtx.writer.Backend#

A loaded NVTXW backend: the module handle plus its interface table.

Do not construct directly; use load_backend().

close(self)#

Finalize and release the backend.

Active sessions, and their open streams, are ended first.

Calling this method is optional because backends normally remain loaded until the process exits. Calling it more than once has no effect. When multiple backends were loaded from the same library, the library is finalized only after every wrapper is closed. Its module remains loaded until process exit.

Raises:

WriterError – If the backend fails to end an active session.

exception nvtx.writer.WriterError(result_code, operation=None)#

Raised when an NVTXW backend call returns a non-success result code.

Parameters:

  • result_code (int) – The NVTXW_RESULT_* code returned by the failing call.

  • operation (str, optional) – Name of the backend call that failed.

result_code#

The raw NVTXW_RESULT_* code returned by the failing call.

Type:

int

operation#

Name of the backend call that failed, if known.

Type:

str or None

Sessions and Streams#

class nvtx.writer.Session(name, backend, *, config=None)#

An NVTXW session: the top-level container data is written into.

Use as a context manager (recommended) or call begin() and end() explicitly.

Parameters:

  • name (str or bytes) – Session name. Tools may display it or use it to name a file or directory representing the session.

  • backend (Backend) – Backend the session writes to, from load_backend().

  • config (str or bytes, optional) – Backend-specific configuration options, one key=value pair per line. Backends use reasonable defaults for options not provided and ignore keys they do not support.

Notes

Writes to distinct streams may proceed concurrently. Calls on the same stream must not overlap unless the caller synchronizes them. Registration and lifecycle operations must not overlap writes: complete setup before starting writer threads, and stop them before closing streams or ending the session.

begin(self)#

Start the session.

When applicable, prefer using a context manager (with Session("my session", backend=backend) as session:) over calling this method explicitly.

Raises:

  • RuntimeError – If the session is already active or the backend is closed.

  • WriterError – If the backend fails to begin the session.

create_stream(
self,
name,
*,
domain=None,
scope=None,
time_domain_id=NVTX_TIME_DOMAIN_ID_NONE,
interleaving=StreamInterleaving.NONE,
ordering=StreamOrdering.UNKNOWN,
skid=StreamSkid.NONE,
skid_amount=0,
)#

Create a stream associated with this session.

This method configures the stream but does not open it. Use the stream as a context manager or call Stream.open() before writing events.

Parameters:

  • name (str or bytes) – Stream name.

  • domain (Domain, str, bytes, optional) – Domain object or domain name. None selects the session default domain. Names and None are resolved with get_domain().

  • scope (PredefinedScope, Scope, int, or None, optional) – Default scope associated with the stream. Pass PredefinedScope.NONE, PredefinedScope.ROOT, or a dynamic scope returned by Domain.get_scope() for this stream’s domain. An integer must be in the NVTX static scope ID range.

  • time_domain_id (TimestampType or int, optional) – Time domain used by event timestamps.

  • interleaving (StreamInterleaving, optional) – Whether ordering guarantees apply across the stream or per scope.

  • ordering (StreamOrdering, optional) – Ordering guarantee for events in the stream.

  • skid (StreamSkid, optional) – Unit used to express the partial-sort skid.

  • skid_amount (int, optional) – Maximum partial-sort skid in the unit selected by skid.

Returns:

A configured, unopened stream.

Return type:

Stream

Raises:

  • RuntimeError – If the session is not active or the domain is no longer valid.

  • TypeError – If interleaving, ordering, skid, or time_domain_id has an unsupported type, or scope is not a supported stream scope.

  • ValueError – If domain belongs to a different session, scope is registered in a different domain, or a runtime-resolved predefined scope or an integer outside the static scope ID range is provided.

end(self)#

End the session.

Streams still open in this session are closed first. Objects created from the session (domains, streams, registered strings, scopes, and counters) become invalid when it ends.

When applicable, prefer using a context manager (with Session("my session", backend=backend) as session:) over calling this method explicitly.

Raises:

  • RuntimeError – If the session is not active or the backend is closed.

  • WriterError – If the backend fails to close a stream or end the session.

get_domain(self, name=None)#

Get or create a domain within this session.

Parameters:

name (str or bytes, optional) – Domain name. None or an empty name selects the session’s default domain.

Returns:

The requested domain. Repeated calls with the same name return the same object.

Return type:

Domain

Raises:

  • RuntimeError – If the session is not active.

  • TypeError – If name is not a str, bytes, or None.

  • WriterError – If the backend fails to register the domain.

class nvtx.writer.Domain#

Session-owned NVTX domain. Created by Session.get_domain(). Valid until the owning session ends.

get_category_id(self, name: str | bytes)#

Get or create a named category in this domain.

Parameters:

name (str or bytes) – Category name.

Returns:

The category ID. IDs start at 1 because 0 represents no category, and skip integer category values already passed to this domain’s event write methods. Results are cached per domain.

Return type:

int

Raises:

  • RuntimeError – If the domain is no longer valid.

  • TypeError – If name is not a string or bytes object.

  • WriterError – If the backend fails to register the category.

get_counter(
self,
name,
dtype,
*,
description=None,
scope=None,
semantics=None,
)#

Get or create a counter or counter group in this domain.

Parameters:

  • name (str or bytes) – Display name for the counter.

  • dtype (int, float, or dtype-like) – Counter value type. int records signed 64-bit integer samples, float records double-precision samples, and a NumPy dtype-like object records samples with that dtype. Top-level fixed-size array dtypes are not supported. A structured dtype describes a flat counter group. Its fields may define per-field semantics with nvtx.numpy_dtype() and its counter_semantics argument, and at most one field may have the nvtx.EntryKind.COUNTER_TIMESTAMP role.

  • description (str or bytes, optional) – Longer description for the counter.

  • scope (PredefinedScope, Scope, int, or None, optional) – Scope associated with the counter. Pass a predefined scope, a dynamic scope returned by get_scope(), or an integer in the NVTX static scope ID range.

  • semantics (CounterSemantics, optional) – Semantics for the counter as a whole. For per-field semantics in a structured dtype, use nvtx.numpy_dtype().

Returns:

The requested counter. Results are cached per domain.

Return type:

Counter

Raises:

  • RuntimeError – If NumPy is required but not installed, or the domain is no longer valid.

  • TypeError – If dtype is not dtype-like, is a top-level fixed-size array, or contains nested or array fields, or if scope has an unsupported type.

  • ValueError – If the counter layout contains an unsupported field role, more than one embedded counter timestamp, or scope is registered in a different domain.

  • WriterError – If the backend fails to register the counter or its schema.

get_registered_string(self, string)#

Get or create a registered string in this domain.

Parameters:

string (str or bytes) – String to register.

Returns:

The registered string. Results are cached per domain; str and bytes spellings of the same string share one registration.

Return type:

RegisteredString

Raises:

  • RuntimeError – If the domain is no longer valid.

  • TypeError – If string is not a string or bytes object.

  • WriterError – If the backend fails to register the string.

get_schema(self, dtype, *, kind=None)#

Get or create a payload schema in this domain.

Parameters:

  • dtype (dtype-like) – NumPy dtype describing the payload layout. In an event schema, fields define their roles with nvtx.numpy_dtype() and its entry_kind argument, and may define specially interpreted integer fields with its entry_type argument.

  • kind (EventKind, optional) – Event family described by the schema; required for use with Stream.write_event() and Stream.write_event_batch(). The ID-correlated EventKind.RANGE_START and EventKind.RANGE_END families require exactly one field annotated with PayloadEntryType.RANGE_ID. None creates a generic payload schema.

Returns:

The registered schema. Results are cached per domain, dtype, and kind.

Return type:

Schema

Raises:

  • RuntimeError – If numpy is not installed or the domain is no longer valid.

  • TypeError – If dtype is not dtype-like, or kind is not an nvtx.EventKind or None. For event schemas, if the dtype is not structured, a field uses managed storage or a non-native byte order, or a timestamp role field is not a 64-bit integer.

  • ValueError – If kind cannot be described by a dtype, or the dtype’s timestamp roles do not match kind.

  • WriterError – If the backend fails to register the schema.

get_scope(self, path, *, parent=None)#

Get or create a scope in this domain.

Parameters:

  • path (str or bytes) – Path of the scope relative to parent.

  • parent (PredefinedScope or Scope, optional) – Parent scope. None places the scope at the domain root. The predefined parents may be PredefinedScope.NONE, PredefinedScope.ROOT, PredefinedScope.CURRENT_HW_MACHINE, or PredefinedScope.CURRENT_VM.

Returns:

The registered scope. Results are cached for each path and parent pair.

Return type:

Scope

Raises:

  • RuntimeError – If the domain is no longer valid.

  • TypeError – If parent is not a PredefinedScope, a Scope, or None.

  • ValueError – If parent is registered in a different domain or is not a supported predefined parent scope.

  • WriterError – If the backend fails to register the scope.

class nvtx.writer.Stream#

NVTXW stream: the object events and counter samples are written to.

Created by Session.create_stream(). Use as a context manager (recommended) or call open() and close() explicitly before and after writing data.

close(self)#

Close the stream without ending its session.

Raises:

  • RuntimeError – If the stream is not open or the backend is closed.

  • WriterError – If the backend fails to close the stream.

open(self)#

Open the stream for writing.

Raises:

  • RuntimeError – If the stream is already open or its domain is no longer valid.

  • WriterError – If the backend fails to open the stream.

write_counter_batch(
self,
Counter counter,
data,
*,
timestamps=None,
ordering=BatchOrdering.SORTED,
)#

Write a batch of counter samples.

Timestamps come from one of two sources, selected by the counter’s registered layout:

  • Separate: timestamps is an iterable of per-sample timestamps, same length as data, and data carries the values only. Required unless the layout embeds a timestamp field.

  • Embedded: the counter-group layout has an entry_kind=nvtx.EntryKind.COUNTER_TIMESTAMP field and each row in data carries it; timestamps must be omitted.

Parameters:

  • counter (Counter) – Counter returned by Domain.get_counter() for this stream’s domain.

  • data (numpy.ndarray, pandas.DataFrame, or iterable) – Sample rows. For scalar counters, this is an iterable of values. DataFrame columns are matched to counter fields by name.

  • timestamps (iterable of int, optional) – Timestamp for each sample. Required unless the counter layout contains an embedded counter timestamp and otherwise must be omitted.

  • ordering (BatchOrdering, optional) – Timestamp ordering of the samples. The default is BatchOrdering.SORTED.

Raises:

  • RuntimeError – If the stream is not open, the backend is closed, or NumPy is not installed.

  • TypeError – If counter is not a Counter or ordering is not a BatchOrdering.

  • ValueError – If counter belongs to another domain, the timestamp source is invalid, data is empty, data or timestamps is not one-dimensional, or their lengths differ.

  • WriterError – If the backend fails to write the batch.

write_counter_sample(
self,
Counter counter,
int64_t timestamp,
value,
)#

Write a single counter sample.

Parameters:

  • counter (Counter) – Counter returned by Domain.get_counter() for this stream’s domain.

  • timestamp (int) – Sample timestamp in the stream’s time domain.

  • value – Sample value matching the counter’s registered layout. For a counter group, this contains one row of field values.

Raises:

  • RuntimeError – If the stream is not open or the backend is closed.

  • TypeError – If counter is not a Counter.

  • ValueError – If counter belongs to another domain, its layout embeds a counter timestamp, or value does not contain exactly one sample.

  • WriterError – If the backend fails to write the sample.

Notes

A structured sample is converted to a contiguous array on each call. For high write rates, prefer write_counter_batch().

write_counter_sample_no_value(
self,
Counter counter,
int64_t timestamp,
reason,
)#

Write a counter sample with no explicit value.

Parameters:

  • counter (Counter) – Counter returned by Domain.get_counter() for this stream’s domain.

  • timestamp (int) – Sample timestamp in the stream’s time domain.

  • reason (CounterNoValueReason) – Reason the sample has no explicit value.

Raises:

  • RuntimeError – If the stream is not open or the backend is closed.

  • TypeError – If counter is not a Counter or reason is not a nvtx.CounterNoValueReason.

  • ValueError – If counter belongs to another domain.

  • WriterError – If the backend fails to write the sample.

write_end(self, timestamp, range_id)#

Write the end of a start/end range.

Parameters:

  • timestamp (int) – Range end timestamp in the stream’s time domain.

  • range_id (int) – Identifier passed to the matching write_start() call.

Raises:

  • RuntimeError – If the stream is not open or the backend is closed.

  • WriterError – If the backend fails to write the event.

write_event(self, Schema schema, row)#

Write an event described by a role-annotated dtype schema.

All event families are supported. The ID-correlated EventKind.RANGE_START and EventKind.RANGE_END schemas include a PayloadEntryType.RANGE_ID field.

Parameters:

  • schema (Schema) – Event schema returned by Domain.get_schema() with a kind, for this stream’s domain.

  • row (array-like) – Values for one row of the schema’s dtype, such as a tuple or a NumPy scalar.

Raises:

  • RuntimeError – If the stream is not open or the backend is closed.

  • TypeError – If schema is not a Schema.

  • ValueError – If schema belongs to another domain or is not an event schema, or row does not contain exactly one event.

  • WriterError – If the backend fails to write the event.

Notes

Each call converts row to a contiguous array. For high write rates with a complete-event schema, prefer write_event_batch().

write_event_batch(
self,
Schema schema,
rows,
*,
ordering=BatchOrdering.SORTED,
)#

Write a batch of complete events.

Parameters:

  • schema (Schema) – Complete-event schema returned by Domain.get_schema() with a kind of EventKind.MARK, EventKind.RANGE_PUSHPOP, or EventKind.RANGE_STARTEND, for this stream’s domain.

  • rows (numpy.ndarray, pandas.DataFrame, or iterable) – Event rows. DataFrame columns are matched to fields by name.

  • ordering (BatchOrdering, optional) – Timestamp ordering of the rows. The default is BatchOrdering.SORTED.

Raises:

  • RuntimeError – If the stream is not open or the backend is closed.

  • TypeError – If schema is not a Schema or ordering is not a BatchOrdering.

  • ValueError – If schema belongs to another domain or is not a complete-event schema, or rows contains no events.

  • WriterError – If the backend fails to write the batch.

write_mark(
self,
timestamp,
*,
message=None,
color=None,
category=None,
)#

Write a mark event.

Parameters:

  • timestamp (int) – Event timestamp in the stream’s time domain.

  • message (str, bytes, or RegisteredString, optional) – Message associated with the event.

  • color (int or color-like, optional) – Event color. Integers are interpreted as ARGB values.

  • category (str, bytes, or int, optional) – Event category. A name is registered in the stream’s domain.

Raises:

  • RuntimeError – If the stream is not open or the backend is closed.

  • TypeError – If message or category has an unsupported type.

  • ValueError – If an integer category is outside [0, 2**32 - 1], or message is a RegisteredString from a different domain.

  • WriterError – If the backend fails to write the event.

write_pop(self, timestamp)#

Write the end of the most recently pushed range.

Parameters:

timestamp (int) – Range end timestamp in the stream’s time domain.

Raises:

  • RuntimeError – If the stream is not open or the backend is closed.

  • WriterError – If the backend fails to write the event.

write_push(
self,
timestamp,
*,
message=None,
color=None,
category=None,
)#

Write the beginning of a push/pop range.

Push/pop ranges are nested and pair in last-in, first-out order.

Parameters:

  • timestamp (int) – Range start timestamp in the stream’s time domain.

  • message (str, bytes, or RegisteredString, optional) – Message associated with the range.

  • color (int or color-like, optional) – Range color. Integers are interpreted as ARGB values.

  • category (str, bytes, or int, optional) – Range category. A name is registered in the stream’s domain.

Raises:

  • RuntimeError – If the stream is not open or the backend is closed.

  • TypeError – If message or category has an unsupported type.

  • ValueError – If an integer category is outside [0, 2**32 - 1], or message is a RegisteredString from a different domain.

  • WriterError – If the backend fails to write the event.

write_pushpop(
self,
start,
end,
*,
message=None,
color=None,
category=None,
)#

Write a complete push/pop range event.

Parameters:

  • start (int) – Range start timestamp in the stream’s time domain.

  • end (int) – Range end timestamp in the stream’s time domain.

  • message (str, bytes, or RegisteredString, optional) – Message associated with the range.

  • color (int or color-like, optional) – Range color. Integers are interpreted as ARGB values.

  • category (str, bytes, or int, optional) – Range category. A name is registered in the stream’s domain.

Raises:

  • RuntimeError – If the stream is not open or the backend is closed.

  • TypeError – If message or category has an unsupported type.

  • ValueError – If an integer category is outside [0, 2**32 - 1], or message is a RegisteredString from a different domain.

  • WriterError – If the backend fails to write the event.

write_start(
self,
timestamp,
range_id,
*,
message=None,
color=None,
category=None,
)#

Write the beginning of a start/end range.

The range is paired with a subsequent write_end() call that uses the same range_id.

Parameters:

  • timestamp (int) – Range start timestamp in the stream’s time domain.

  • range_id (int) – Nonzero identifier used to pair the start with its end.

  • message (str, bytes, or RegisteredString, optional) – Message associated with the range.

  • color (int or color-like, optional) – Range color. Integers are interpreted as ARGB values.

  • category (str, bytes, or int, optional) – Range category. A name is registered in the stream’s domain.

Raises:

  • RuntimeError – If the stream is not open or the backend is closed.

  • TypeError – If message or category has an unsupported type.

  • ValueError – If range_id is zero, an integer category is outside [0, 2**32 - 1], or message is a RegisteredString from a different domain.

  • WriterError – If the backend fails to write the event.

write_startend(
self,
start,
end,
*,
message=None,
color=None,
category=None,
)#

Write a complete start/end range event.

Parameters:

  • start (int) – Range start timestamp in the stream’s time domain.

  • end (int) – Range end timestamp in the stream’s time domain.

  • message (str, bytes, or RegisteredString, optional) – Message associated with the range.

  • color (int or color-like, optional) – Range color. Integers are interpreted as ARGB values.

  • category (str, bytes, or int, optional) – Range category. A name is registered in the stream’s domain.

Raises:

  • RuntimeError – If the stream is not open or the backend is closed.

  • TypeError – If message or category has an unsupported type.

  • ValueError – If an integer category is outside [0, 2**32 - 1], or message is a RegisteredString from a different domain.

  • WriterError – If the backend fails to write the event.

Registered Objects#

class nvtx.writer.RegisteredString#

Wrapper for nvtxStringHandle_t, created by Domain.get_registered_string().

Pass to the single-event range/mark write methods in place of a str message to emit a registered-string handle instead of an inline UTF-8 message. The numeric handle can also be stored in a payload field annotated with nvtx.PayloadEntryType.REGISTERED_STRING. Valid until the owning session ends.

class nvtx.writer.Scope#

Wrapper for a registered scope ID. Created by Domain.get_scope(). Valid until the owning session ends.

path#

The path the scope was registered with (None if unnamed).

scope_id#

Registered scope ID within the domain.

class nvtx.writer.Schema#

Domain-owned payload schema handle. Created by Domain.get_schema(). Pass event schemas (created with a kind) to Stream.write_event() and Stream.write_event_batch(). Valid until the owning session ends.

dtype#

The NumPy dtype the schema was registered with.

kind#

The schema’s EventKind, or None if generic.

schema_id#

Registered schema ID within the domain.

class nvtx.writer.Counter#

Domain-owned counter handle. Created by Domain.get_counter(). Pass to the Stream counter write methods. Valid until the owning session ends.

counter_id#

Registered counter ID within the domain.

description#

The counter’s description, or None.

dtype#

The normalized dtype the counter was registered with.

name#

The counter’s display name.

semantics#

The counter’s nvtx.CounterSemantics, or None.

Stream Options#

class nvtx.writer.StreamInterleaving(*values)#

Whether ordering guarantees apply across the whole stream or per scope.

class nvtx.writer.StreamOrdering(*values)#

How fully events are sorted in the stream.

class nvtx.writer.StreamSkid(*values)#

How partial-sort “skid” is quantified (paired with skid_amount).

class nvtx.writer.PredefinedScope#

Alias of nvtx.PredefinedScope.