Module observability 

Native typed runtime observations and bounded query-local capture.

Modules

graph_observation

Measured graph-execution observation.

Structs

AdmissionRequestId

Service-local identity for one admission attempt.

AttemptAdmissionFact

Immutable device grant and wait duration committed by admission.

AttemptAdmissionWaitFact

Final queue state captured when a queued admission receives its immutable grant.

AttemptComposedScheduleProjection

Immutable composed memory schedule bound to an admitted attempt.

AttemptFailureSummary

Bounded retained classification for a primary terminal failure.

AttemptFinalDomainUsage

Exact final counters observed for one attempt allocation domain.

AttemptId

Opaque execution-attempt identity minted by the runtime. Display and serialization use attempt- followed by 32 hexadecimal digits. The identity is independent of caller query and trace correlations.

AttemptQueryId

Opaque caller query correlation, limited to 256 UTF-8 bytes and required to be non-blank.

AttemptRetryAdvice

One bounded retry/recovery recommendation sealed with an attempt report.

AttemptTimestamps

Attempt lifecycle times in nanoseconds from one monotonic attempt clock. Optional boundaries are absent when they were not recorded. These values are elapsed times, without a wall-clock epoch.

AttemptTraceContext

Opaque caller trace correlation, limited to 1024 UTF-8 bytes and required to be non-blank.

BarrierDefinitionRow

One compiled barrier definition in the static runtime topology.

BudgetWindowPeaks

The largest allocator high-water and retained bytes the budget reports in one window carried.

CleanupFailureSummary

First bounded cleanup failure retained by an attempt lifecycle.

CompiledEdgeRow

One compiled dependency edge in the static runtime topology.

DeterministicRuntimeObservationClock

Deterministic clock for contract tests and controlled simulations.

LakehouseCacheFillEventSnapshot

Credential-free snapshot of a background lakehouse cache-fill completion event.

LiveRuntimeObservationSnapshot

Immutable live snapshot. Its footer is always incomplete and has no terminal outcome.

MetricsRecorder

Records one plan execution’s metrics into its observation owner.

ObservationSequence

Total recorder order assigned to every attempted record.

PlanEdgeRow

One directed edge in the static native plan topology.

PlanExecutionId

Identity for one invocation of a native plan.

PlanNodeRow

One native plan node in the static topology.

QueryAttemptReport

Immutable terminal attempt record published after cleanup and sealing.

RuntimeBarrierId

Compiled pipeline-barrier identity scoped to one plan execution.

RuntimeCleanupFailureObservation

Secondary-cleanup-failure payload body retained out of line.

RuntimeEventContext

Optional event identity attached outside the payload.

RuntimeExecutionObservationScope

Cloneable identity and recording capability for descendants of one plan execution. It deliberately has no seal authority.

RuntimeGpuJobObservation

GPU-job payload body retained out of line.

RuntimeObservationConfig

Query-local recorder configuration.

RuntimeObservationExportError

Typed JSONL export error. Export failure never mutates the sealed snapshot.

RuntimeObservationHandle

Cheaply cloneable recording capability without terminal-seal authority.

RuntimeObservationLimits

Recorder limits copied into the manifest.

RuntimeObservationOwner

Cloneable shared ownership of one query observation session.

RuntimeObservationSession

Owner-only capability for one query observation lifetime.

RuntimeOperatorStageGuard

Exactly-once Started/terminal guardian for one operator substage.

RuntimeOperatorStageIdentity

Stable identities that travel with every Started/terminal pair.

RuntimePipelineEdgeId

Compiled-pipeline edge identity scoped to one plan execution.

RuntimePlanExecutionLifecycle

One plan invocation inside a query whose owner outlives native execution.

RuntimePlanNodeId

Plan-node identity scoped to one plan execution.

RuntimeQueryLifecycle

Owner-only query lifecycle. Normal completion consumes the owner; Drop terminalizes abandoned and unwinding executions without exposing seal authority to workers.

RuntimeReservationId

Reservation identity scoped to one plan execution.

RuntimeReservationObservation

Context-rich reservation payload body retained out of line.

RuntimeResourceId

Resident-resource identity scoped to one plan execution.

RuntimeResourceRow

One resident resource in the static runtime topology.

RuntimeSinkId

Compiled pipeline-sink identity scoped to one plan execution.

RuntimeSourceReadObservation

Source-read payload body retained out of line.

RuntimeSpanId

Span identity scoped to one query.

RuntimeStreamLeaseScope

Explicit correlation available when a service-stream lease is acquired.

RuntimeTaskId

Compiled task identity scoped to one native plan invocation.

RuntimeTaskLifecycle

Exactly-once lifecycle for one compiled task attempt.

RuntimeTimelineEvent

One dynamic event in recorder total order.

RuntimeWorkerId

Worker identity scoped to one query.

SealedAttemptLabels

Stable fixed-cardinality labels derived from one sealed attempt projection.

SealedAttemptProjection

Bounded projection of facts from one already-sealed attempt report.

SealedRuntimeObservationSnapshot

Immutable sealed snapshot accepted by the JSONL exporter.

SinkDefinitionRow

The compiled result-sink definition in the static runtime topology.

SourceReadTotals

Exact source-read totals for one query.

TaskDefinitionRow

One compiled task definition in the static runtime topology.

WorkerDefinitionRow

One host worker definition used by GPU or source execution.

Enums

AttemptAllocatorEventSource

Closed source category copied from one cuDF allocator-ring record.

AttemptCapacityDisposition

Ownership of admitted capacity after the terminal release commit.

AttemptCleanupDisposition

Cleanup result fixed before the terminal report is published.

AttemptDisposition

Execution coverage assigned after planning, independently of terminal outcome.

AttemptEvidenceProvenance

How one bounded resource-evidence field was obtained.

AttemptFailureFactKey

Stable allowlisted fact keys for bounded failure summaries.

AttemptFailureFactValue

Stable allowlisted fact values for bounded failure summaries.

AttemptFailureOperation

Coarse owning operation for a stable failure projection.

AttemptFailureStatus

Closed stability/recovery status for a report-visible failure.

AttemptHealthTransition

The device-health result decided by an admitted attempt’s terminal release commit.

AttemptRetryPrerequisite

Closed condition that must hold before acting on an AttemptRetryRecovery recommendation.

AttemptRetryRecovery

Closed recovery action advised by one sealed attempt report.

CleanupFailurePhase

Closed lifecycle phase at which a secondary cleanup failure occurred.

GpuJobLifecycleState

GPU execution-pool job lifecycle state.

PlanExecutionBoundaryKind

Plan-execution observation boundary.

QueryBoundaryKind

Query-level observation boundary.

RuntimeObservationExportErrorKind

Machine-readable export failure category.

RuntimeObservationExportErrorStatus

Retry status derived from the export failure.

RuntimeObservationLossReason

Reason an attempted record was not retained.

RuntimeObservationPayload

Typed dynamic event payload.

RuntimeObservationRecord

One independently parseable JSONL record.

RuntimeObservationRecordClass

Retention class used by explicit loss accounting.

RuntimeObservationRecordDisposition

Infallible result of one hot-path record attempt.

RuntimeOperatorStageKind

Operator-substage category for blocking native primitives.

RuntimeOperatorStageState

Lifecycle state for one operator-substage span.

RuntimeReservationAction

Reservation operation recorded at the ownership boundary that applied it.

RuntimeReservationDisposition

Terminal or nonterminal ownership disposition for a reservation operation.

RuntimeResourceDomain

Resource domain carried by a static resource definition.

RuntimeTerminalOutcome

Query terminal outcome stored outside the bounded record collection.

RuntimeTopologyRecord

Static topology accepted by the bounded recorder.

SourceReadFact

One source-read fact, recorded once at the boundary that owns it.

SourceReadLifecycleState

Source-read scheduler lifecycle state.

StreamLeaseLifecycleState

Service stream-lease lifecycle state.

TaskLifecycleState

Exactly-once lifecycle state for one compiled task attempt.

Constants

COMPOSED_SCHEDULE_PROJECTION_SCHEMA

MAX_ATTEMPT_QUERY_ID_BYTES

Maximum UTF-8 byte length for caller-supplied attempt query correlation.

MAX_ATTEMPT_TRACE_CONTEXT_BYTES

Maximum UTF-8 byte length for caller-supplied opaque trace context.

QUERY_ATTEMPT_REPORT_SCHEMA

Schema label of QueryAttemptReport. Decoding rejects every other label.

RUNTIME_OBSERVATION_JSONL_SCHEMA

JSONL schema emitted by sealed runtime observation snapshots.

SEALED_ATTEMPT_PROJECTION_SCHEMA

Schema label for the bounded public projection of a sealed attempt report.

Functions

stage_context_from_execution

Returns the observation handle, plan execution id, and parent span id of a runtime execution scope.

task_attempt_id

Builds one task-attempt identity from an explicit task and attempt number.

write_runtime_observation_jsonl

Writes a sealed snapshot as ordered, independently parseable JSONL records.