Events and observation

Parameters

hook

Callable invoked with ExecEvent values as Cuprum executes commands and pipelines.

Returns

HookRegistration

A handle that can be detached or used as a context manager.

Attributes

phase

Event phase. See ExecPhase. Both timeout and teardown_error are ancillary diagnostics that never displace a lifecycle phase. pipeline_fail_fast reports the pipeline coordinator's decision before the failing stage's own exit event. settled is the single definitive terminal event for every execution that emitted plan. It carries terminal_outcome, an optional pid, and exec_id. exit_code is a real child status only when one is available; it stays None for spawn failure and cancellation paths that do not produce a command result. The event never carries an exception payload. Catalogue lookup failures raised as UnknownProgramError in catalogue and allowlist failures from _enforce_allowlist happen before exec_id is minted and are outside this terminal-event contract. timeout marks a run that exceeded its deadline, and is emitted before the existing exit event and the public TimeoutExpired, both of which are preserved. teardown_error marks a stream consumer that drained with an unexpected error during cleanup. capture_eof_grace_expired marks a capturing drain whose bounded EOF grace elapsed while one or two readers remained pending. Neither ancillary diagnostic carries an ordering guarantee. Cleanup also runs on external cancellation and on an unexpected stdin-writer failure, and on those paths the original exception propagates unchanged: no exit event follows and no TimeoutExpired is raised, so an ancillary diagnostic may be the last event a consumer sees for that execution. stdio_error is the best-effort counterpart to stdin_error for the standard-stream boundaries that fail *outside* the stdin writer's own pipe operations: the caller's producer, an invalid chunk, the encoder, opening a cuprum-owned target file, and flushing a caller's borrowed file object. It is emitted where the failing boundary is known, and never in place of the caller-visible exception — a producer failure still raises StdinSourceError with the producer's own exception chained, and a failed owned-path open still raises the OSError _open_owned_path builds. It carries error_category rather than an exception message, because several of these boundaries raise the same exception type and the category is what separates them.

program

The allowlisted program that is executing.

argv

Full argv including program name as the first element. Empty for the sanitized pipeline_fail_fast decision event.

cwd

Working directory for the subprocess, when set. Absent from the sanitized pipeline_fail_fast decision event.

env

Environment overlay provided for this execution, when set. Absent from the sanitized pipeline_fail_fast decision event.

pid

Process identifier for the running subprocess, when reported. plan always carries None. A settled event can also carry None when startup failed before a process existed or cancellation ended the run before a result was available.

timestamp

Wall-clock timestamp (seconds since epoch) when the phase occurred.

line

Output line for stdout / stderr phases. Line terminators are omitted.

exit_code

Real child exit code for exit and, when available, settled phases, and the failing stage's exit code for pipeline_fail_fast. It is None when no child status is available, including spawn failure and cancellation paths that do not produce a command result.

duration_s

Elapsed duration in seconds from start to subprocess exit (not including output drain after process termination). For pipeline_fail_fast this is how long the failing stage ran before its completion was observed.

tags

Arbitrary, JSON-like metadata associated with this execution. Empty on the sanitized pipeline_fail_fast decision event.

project

Trusted project name configured for the command. Unlike tags, this value is not caller supplied and therefore remains available on the sanitized pipeline_fail_fast decision event.

note

Optional human-readable diagnostic string for ancillary events such as stdin_error.

byte_count

Number of bytes written for byte-counted phases such as stdin.

operation

For failure and lifecycle events, the operation involved. For stdin_error this is the pipe operation that failed (for example write or close); for timeout it is wait; for teardown_error it is drain.

error_type

For failure events such as stdin_error, timeout, and teardown_error, the class name of the raised exception (for example OSError, TimeoutError). For teardown_error this is the comma-joined class names of the consumer drain failures.

exec_id

Stable per-execution correlation token, minted once per execution and shared by every lifecycle event for that execution. It is the reliable way to correlate an execution's events, because a process identifier (pid) can be recycled by the operating system across executions. None for legacy or manually constructed events that predate the token; such events cannot be safely correlated by consumers.

terminal_outcome

Closed category carried by settled: exit_zero, exit_nonzero, timeout, cancelled, or error. It is None for every other phase and contains no exception details.

timeout_s

For the timeout phase, the configured wall-clock timeout in seconds that was exceeded. None for other phases.

timeout_mode

For the timeout phase, the reason the deadline expired: "elapsed_deadline" when a positive wall-clock deadline elapsed, or "non_positive_immediate" when a non-positive (timeout <= 0) deadline expired immediately without awaiting the process. None for other phases.

stage_index

Zero-based pipeline position of the failing stage for pipeline_fail_fast. This typed field is not derived from tags, which callers may shadow.

stage_count

Pipeline width for pipeline_fail_fast.

eof_grace_s

Fixed capture EOF grace duration for capture_eof_grace_expired.

pending_readers

Number of readers (one or two) still pending when the capture EOF grace elapsed. None for other phases.

max_rss_bytes

Maximum resident set size attributable to this execution's own child, in bytes, as reported by wait4. Carried on the terminal exit event of a direct command on Linux and macOS. None on Windows, on platforms whose child-specific interface is unavailable, on pipeline stages whose concurrently reaped children cannot be separated, and on the aggregate CPU-only fallback — whose RUSAGE_CHILDREN high-water mark spans every reaped child and cannot be attributed to this one. Also None on a timeout terminal event, where the child was signalled rather than reaped by its owner.

user_cpu_seconds

User CPU time in seconds attributable to this execution's child. Populated from the same wait4 result as max_rss_bytes on the attributable path, and from the clamped RUSAGE_CHILDREN delta on the CPU-only fallback. None where neither source applies.

system_cpu_seconds

System CPU time in seconds attributable to this execution's child, from the same sources and under the same conditions as user_cpu_seconds.

resource_usage_mode

How the resource fields above were obtained. See ResourceUsageMode. It is carried so a consumer can tell an attributable measurement from the aggregate fallback and from a platform that measures nothing, without inferring that from a None in max_rss_bytes alone. Every terminal exit event carries a mode: wait4_child or aggregate_cpu_delta where a source produced figures, and unavailable where none did — Windows, a platform without the child-specific interface, a pipeline stage, and the timeout path, which signals its child rather than reaping it. An unavailable terminal event therefore still distinguishes a platform that cannot measure from one whose samples went missing, which a bare None cannot. The mode is None on every non-terminal phase.

env_mode

The effective environment policy for this execution, once the active context and any per-call policy have been composed. Carried on every phase, because it is known before the child is spawned and describes the whole execution rather than one measurement. A replacement boundary is the reason the field exists: a REPLACE policy discards the live parent environment, so a child that omits PATH can fail to resolve a bare program name before it ever starts. Without the mode, a consumer sees an ordinary spawn failure and cannot tell it apart from an overlay run. None only on legacy or manually constructed events; the execution paths always resolve a mode.

owns_group

Whether the teardown that produced a group_teardown event was signalling the child's whole process group rather than the direct child alone. None for other phases. Carried because the same outcome means different things on the two routes: a group left holding members is a failure the ownership policy introduced, while a direct-child signal that could not be delivered is the behaviour every run had before it.

group_outcome

Closed category for a group_teardown event. See GroupTeardownOutcome. It is this field, rather than note or error_type, that a bounded metric is labelled from, so no pid, path, or error string can reach a metric label. None for other phases.

settle_s

How long the group-settlement wait had run when it expired, carried by a settlement_timeout event. None on the other outcomes, so an absent figure is not read as an instant one.

resolved_path

The executable this execution actually ran, when a scope bound the program's logical identity to a specific path. None when no binding applied, in which case the child ran under the name in argv[0].

error_category

Bounded category naming which failure boundary produced a diagnostic event. See StdioFailureCategory, also re-exported here. Carried on stdio_error; None for every other phase, including the pre-existing stdin_error events, whose operation already names its boundary. It is a typed field rather than part of note because error_type cannot carry it, and the value is low-cardinality, so it is the one failure attribute safe to attach to a metric series. It is the *executable*, not the command: argv still carries the arguments, and program still carries the catalogue identity that policy was checked against. Keeping all three means a consumer can see what was permitted, what was asked for, and what ran, without having to infer one from another. The path is a string rather than a resolved file identity, so a replaced binary is not detected; see the TOCTOU note in cuprum.executable_binding.

capture_mode

The mode this run reports its captures in, carried on every phase for the reason env_mode is: it is decided before the child spawns and describes the whole execution rather than one measurement. Without it a byte-exact run and a text run of the same command emit the same counters and span attributes, so a timeout, teardown failure, or terminal failure cannot be attributed to the mode that hit it. None only on legacy or hand-built events; see CaptureMode.

A field appended to this declaration preserves an existing positional slot only if nothing is inserted *ahead* of that slot: inserting one ahead of exec_id would silently rebind existing positional arguments, handing the correlation token to the new field and leaving exec_id=None — which consumers such as TracingHook treat as uncorrelatable and drop. Nor is appending enough by itself, because declaration follows insertion: terminal_outcome is pinned as the tail by test_terminal_outcome_public_api yet holds a positional slot of its own, so a later field is declared kw_only and inserted immediately before it. That keeps both the pinned tail and every pre-existing slot exactly where they were.

Parameters

logger

Logger instance to emit records to. Defaults to logging.getLogger( "cuprum") when omitted.

start_level

Logging level for the start event (default logging.INFO).

exit_level

Logging level for the exit event (default logging.INFO).

redaction

Optional policy applied to the logged argument vector. Defaults to None. Executed arguments and captured results remain unchanged.

Returns

LoggingHookRegistration

Handle for detaching the hooks manually or via context manager usage.

Parameters

hook

Synchronous callable invoked once for each completed control operation. It must not raise; a failure is logged and swallowed so it cannot replace the control operation's own outcome.

Returns

ControlHookRegistration

A context-local registration handle that supports detach() and context-manager use.

Attributes

operation

Closed operation kind, distinguishing a caller-named signal from a graceful stop and from a forced one.

outcome

Closed completion outcome. escalated identifies a stop that had to send the forced signal after the grace window elapsed.

duration_s

Monotonic elapsed seconds from operation start through completion.

exec_id

The owning run's correlation token, when the handle safely provides one. None for a control operation attempted on a handle whose run carried no token.

signal_number

The POSIX signal the caller named, for signal operations. None for the stop operations, which choose their own signal and report which one ended the child through the settled outcome instead.

pid

The child's process identifier, when the handle had one. It travels on the event so an operator reading a trace can name the process a control operation was aimed at; it must never become a metric label, because a label domain keyed on a PID grows without bound and a recycled PID would fold two unrelated children into one series.

Parameters

hook

A synchronous callable that receives each LineStreamEvent in the active context.

Returns

LineStreamHookRegistration

A scoped registration that detaches the hook on scope exit or explicit LineStreamHookRegistration.detach.

Attributes

phase

One bounded lifecycle state from LineStreamPhase.

exec_id

The execution identifier shared with the corresponding ExecEvent lifecycle.

pid

The child process identifier once spawning has completed.

stream

The output stream related to a queue or sink event, when applicable.

sink

The bounded callback or queue destination related to a sink failure.

queue_size

The queue depth at a saturation boundary, recorded as event data only.

queue_capacity

The finite queue capacity at a saturation boundary.

error_type

The exception class name from a sink failure, never a metric label.

Attributes

SPAWNED

The subprocess and its consumers are ready.

QUEUE_SATURATED

A line sink is waiting for bounded queue capacity.

SINK_FAILED

A callback or queue sink raised while receiving a line.

TIMEOUT

The command deadline expired.

CANCELLED

Iteration or line delivery was cancelled.

TEARDOWN_STARTED

Shared child-process teardown began.

TEARDOWN_COMPLETED

Shared teardown and consumer drainage completed.

COMPLETED

The command result was assembled and is ready to publish.

Parameters

hook

Synchronous callable invoked with each EchoEvent.

Returns

EchoHookRegistration

A handle that can be detached or used as a context manager.

Examples

Count echo failures into a metrics collector::

    from cuprum.adapters.metrics_adapter import InMemoryMetrics
    from cuprum.adapters.echo_metrics import EchoMetricsHook

    metrics = InMemoryMetrics()
    with observe_echo(EchoMetricsHook(metrics)):
        pipeline.run_sync()

Attributes

stream

Which output stream the failing echo belonged to.

error_category

The closed-set category naming why the event occurred.

dropped_bytes

Child-output bytes omitted from a successfully truncated echo line, otherwise None.

Examples

A stdout echo that could not encode its payload::

    event = EchoEvent(
        stream=EchoStream.STDOUT,
        error_category=EchoErrorCategory.UNICODE_ENCODE,
    )
    assert event.stream == "stdout"

Examples

The member value is the string operators see::

    assert EchoStream.STDOUT == "stdout"

Examples

The member value is the string operators see::

    assert EchoErrorCategory.UNICODE_ENCODE == "unicode_encode"
    assert EchoErrorCategory.BROKEN_PIPE == "broken_pipe"

Attributes

stream

Which output stream the handled echo disablement belonged to. The value is the closed-set EchoStream, not free text.

error_category

The closed-set EchoErrorCategory naming why the echo write failed. It is categorical only: the sink's type, its encoding, any exception text, and the subprocess payload never reach the record.

Examples

A stdout echo that could not encode its payload::

    fallback = RelayFallback(
        stream=EchoStream.STDOUT,
        error_category=EchoErrorCategory.UNICODE_ENCODE,
    )
    assert fallback.stream == "stdout"