kempnerpulse.reader

KempnerPulse Layer 1 — Read.

Backends acquire raw data from a single source and emit a stream of opaque RawRecord objects in that source’s own vocabulary. Interpreting those records (canonical names, units, missing-value policy) belongs to Layer 2, not here. make_backend selects a backend from a ReaderConfig.

Functions

make_backend(config)

Construct the backend named by config.backend (imported lazily).

class kempnerpulse.reader.Backend

Bases: Protocol

Layer 1 contract. Implementations: dcgmi, prometheus, replay.

open(config)

Acquire the source (spawn dcgmi, open the HTTP scrape, open the replay file).

Backends that contend for a shared resource (dcgmi profiling watch) run their preflight here and raise a typed ReaderError with remediation on failure.

Parameters:

config (ReaderConfig)

Return type:

None

stream()

Yield RawRecord objects until the source is exhausted or close() is called.

Return type:

Iterator[RawRecord]

close()

Release the source. Must be safe to call after a failed open().

Return type:

None

property caps: BackendCaps

Static capabilities (kind + producible source fields).

__init__(*args, **kwargs)

class kempnerpulse.reader.BackendCaps

Bases: object

What a backend can produce.

fields is the set of source field names this backend can emit. Layer 2 uses it to decide which canonical metrics are available for a given source.

kind: BackendKind

fields: frozenset[str]

__init__(kind, fields=<factory>)

Parameters:

• kind (BackendKind)

• fields (frozenset[str])

Return type:

None

class kempnerpulse.reader.BackendKind

Bases: Enum

Which Layer-1 source produced a record.

DCGMI = 'dcgmi'

PROMETHEUS = 'prometheus'

REPLAY = 'replay'

NVML_DIRECT = 'nvml_direct'

class kempnerpulse.reader.RawRecord

Bases: object

One reading for one entity (a GPU or MIG slice), in the source’s vocabulary.

fields carries the source’s raw key/values for this entity — metric values (typically float) and any source labels (str). A value is None when the source reported N/A; it is never silently coerced to 0. Assigning meaning to these keys (canonical names, units, identity) is Layer 2’s job.

timestamp: float

wallclock: float

entity_id: str

fields: Mapping[str, Any | None]

source: str

source_version: str

error: str | None = None

__init__(timestamp, wallclock, entity_id, fields, source, source_version, error=None)

Parameters:

• timestamp (float)

• wallclock (float)

• entity_id (str)

• fields (Mapping[str, Any | None])

• source (str)

• source_version (str)

• error (str | None)

Return type:

None

class kempnerpulse.reader.ReaderConfig

Bases: object

Minimal Layer-1 configuration.

A deliberately small, self-contained slice of configuration so that Layer 1 can be constructed and tested on its own. The cross-cutting configuration tier supplies these values from parsed CLI arguments.

backend: BackendKind = 'dcgmi'

poll_seconds: float = 0.1

source: str = 'http://localhost:9400/metrics'

gpu_ids: tuple[str, ...] | None = None

all_gpus: bool = False

timeout: float = 5.0

__init__(backend=BackendKind.DCGMI, poll_seconds=0.1, source='http://localhost:9400/metrics', gpu_ids=None, all_gpus=False, timeout=5.0)

Parameters:

• backend (BackendKind)

• poll_seconds (float)

• source (str)

• gpu_ids (tuple[str, ...] | None)

• all_gpus (bool)

• timeout (float)

Return type:

None

exception kempnerpulse.reader.ReaderError

Bases: RuntimeError

Base for Layer-1 read failures. Carries an actionable remediation string.

__init__(message, remediation='')

Parameters:

• message (str)

• remediation (str)

Return type:

None

exception kempnerpulse.reader.HostEngineUnavailableError

Bases: ReaderError

nv-hostengine is not reachable on the local socket.

exception kempnerpulse.reader.ExporterCollisionDetected

Bases: ReaderError

dcgm-exporter already holds the profiling watch; recommend --backend prometheus.

exception kempnerpulse.reader.ReservationDeniedError

Bases: ReaderError

Could not acquire the requested DCGM watch fields without dropping another consumer.

exception kempnerpulse.reader.DcgmStreamError

Bases: ReaderError

The dcgmi dmon streaming subprocess failed or exited unexpectedly.

kempnerpulse.reader.make_backend(config)

Construct the backend named by config.backend (imported lazily).

Parameters:

config (ReaderConfig)

Return type:

Backend

Modules

base	Layer 1 (Read) — backend contract and raw records.
dcgmi	Layer 1 (Read) — direct DCGM backend (dcgmi dmon).
preflight	Layer 1 (Read) — preflight checks for the direct DCGM backend.
prometheus	Layer 1 (Read) — Prometheus backend (dcgm-exporter /metrics).
replay	Layer 1 (Read) — replay backend.