stormlog.infer.trace_import

Import profiler traces (Kineto, Nsight Systems) into an inference artifact.

The artifact’s infer.artifact record supplies the run and session. Each trace is registered in the run envelope and its GPU activity is appended as infer.activity_ref records through append_inference_capture.

Functions

`artifact_run_identity`(path)	Return the run and session IDs recorded by the artifact's identity record.
`combine_captures`(captures)	Merge per-trace captures; a capability is collected if any trace had it.
`import_traces_into_artifact`(artifact, traces, *)	Append the traces' GPU activity to `artifact` and return what was added.
`imported_trace_paths`(artifact)	Resolved paths of the traces whose GPU activity the artifact already holds.
`parse_device_uuids`(values)	Parse `[TRACE_FILE:]INDEX=UUID` entries; a bare `UUID` means device 0.
`trace_attachment_id`(path[, prefix])	A stable ID per file: its name and a digest of its resolved path.

Classes

`DeviceUuids`([shared, per_trace, bound])	GPU UUIDs by CUDA ordinal: shared by every trace, or for one trace.
`TraceFileCollector`(paths, *[, device_uuids, ...])	A `TraceCollector` over profiler trace files, chosen by file type.

class stormlog.infer.trace_import.DeviceUuids(shared=<factory>, per_trace=<factory>, bound=False)[source]

Bases: object

GPU UUIDs by CUDA ordinal: shared by every trace, or for one trace.

An ordinal is local to the traced process (after CUDA_VISIBLE_DEVICES), so a shared mapping is only safe when each ordinal belongs to one process. per_trace is keyed by the selector as given until bind matches each selector to one trace; from then on it is keyed by the trace’s resolved path.

Parameters:

shared (dict[int, str])
per_trace (dict[str, dict[int, str]])
bound (bool)

shared: dict[int, str]

per_trace: dict[str, dict[int, str]]

bound: bool = False

bind(paths)[source]

Match every selector to exactly one of paths, or refuse.

A selector is a trace’s path, as given or resolved, or its file name when only one of paths has that name. A selector that names no trace, or a name that several traces share, is a usage error.

Parameters:: paths (Sequence[str | Path])
Return type:: DeviceUuids

scoped(path)[source]

The entries given for this trace alone.

Parameters:: path (str | Path)
Return type:: dict[int, str]

for_trace(path)[source]

Shared entries, overridden by the ones given for this trace.

Parameters:: path (str | Path)
Return type:: dict[int, str]

class stormlog.infer.trace_import.TraceFileCollector(paths, *, device_uuids=None, detail='launch', max_bytes=None, worker_index=None)[source]

Bases: object

A TraceCollector over profiler trace files, chosen by file type.

.sqlite files are read as Nsight Systems exports; .nsys-rep reports are registered but not read (export them to SQLite first); anything else is read as a Kineto Chrome trace.

Parameters:

paths (Sequence[str | Path])
device_uuids (DeviceUuids | dict[int, str] | None)
detail (Detail)
max_bytes (int | None)
worker_index (WorkerIndex | None)

collect(*, run_id, session_id)[source]

Parameters:

run_id (str)
session_id (str)

Return type:

TraceCapture

stormlog.infer.trace_import.artifact_run_identity(path)[source]

Return the run and session IDs recorded by the artifact’s identity record.

Parameters:: path (str | Path)
Return type:: tuple[str, str]

stormlog.infer.trace_import.combine_captures(captures)[source]

Merge per-trace captures; a capability is collected if any trace had it.

Parameters:: captures (Sequence[TraceCapture])
Return type:: TraceCapture

stormlog.infer.trace_import.import_traces_into_artifact(artifact, traces, *, device_uuids=None, detail='launch', envelope_path=None, execution_dir=None)[source]

Append the traces’ GPU activity to artifact and return what was added.

A trace this artifact already imported from the same file is skipped and listed in the summary’s already_imported; importing it again would only duplicate its records. A trace that was only registered, for example over a size bound, can still be imported. execution_dir is the vLLM execution hook’s directory, whose worker hellos name each traced process’s GPU.

Parameters:

artifact (str | Path)
traces (Sequence[str | Path])
device_uuids (DeviceUuids | dict[int, str] | None)
detail (Literal['kernel', 'launch'])
envelope_path (str | Path | None)
execution_dir (str | Path | None)

Return type:

TraceCapture

stormlog.infer.trace_import.imported_trace_paths(artifact)[source]

Resolved paths of the traces whose GPU activity the artifact already holds.

Read from the trace collectors’ capability summaries, which name each trace’s file; a trace registered without being parsed does not count.

Parameters:: artifact (str | Path)
Return type:: set[Path]

stormlog.infer.trace_import.parse_device_uuids(values)[source]

Parse [TRACE_FILE:]INDEX=UUID entries; a bare UUID means device 0.

The index is the CUDA device ordinal inside the traced process, after CUDA_VISIBLE_DEVICES. It is not necessarily the host’s NVML index. A TRACE_FILE prefix limits the entry to one trace: the trace’s path as passed to the command, or its file name when only one trace has it. DeviceUuids.bind checks the prefixes against the traces.

Parameters:: values (Sequence[str])
Return type:: DeviceUuids

stormlog.infer.trace_import.trace_attachment_id(path, prefix='kineto')[source]

A stable ID per file: its name and a digest of its resolved path.

The name alone would make run-a/rank0.pt.trace.json.gz and run-b/rank0.pt.trace.json.gz the same attachment.

Parameters:

path (Path)
prefix (str)

Return type:

str