Skip to navigation
ReferenceAPIsRust Library Referencenemo-relay

Module diagnostics

View as Markdown

Generated from cargo doc --no-deps -p nemo-relay -p nemo-relay-adaptive -p nemo-relay-pii-redaction -p nemo-relay-ffi -p nemo-relay-types -p nemo-relay-plugin -p nemo-relay-worker-proto -p nemo-relay-worker.

Bounded, process-local diagnostic evidence, independent of logger startup.

Startup composition chooses collection once. Disabled handles skip lazy work; enabled components reserve summaries before recording. Recent evidence uses a shared circular history and a reclaimable detail pool. Neither history loss nor output delivery changes accepted numeric totals. Diagnostic evidence never assigns readiness, recovery, or deployment health.

The backing-storage budget excludes caller-owned inputs, producer handles, independently decoded snapshot copies, allocator overhead, and user callback captures. Existing operational output and legacy reports have separate budgets.

Startup and recording

Select settings once before giving producers their handles. Install the chosen context with Diagnostics::install_process_default before using convenience constructors, or inject it explicitly into logging and plugin composition. Neither path requires logging to initialize first.

use nemo_relay::diagnostics::*;
let diagnostics = Diagnostics::from_settings(
    SourceIdentity {
        instance_id: uuid::Uuid::now_v7(),
        process_id: Some(std::process::id()),
        process_role: "embedded".into(),
        relay_version: env!("CARGO_PKG_VERSION").into(),
    },
    DiagnosticsSettings { enabled: true, ..Default::default() },
)?;
let code = BuiltinDiagnosticCode::Failure(FailureCode::Logging(LoggingFailureCode::SinkWriteFailed));
let recorder = diagnostics.register_component(ComponentRegistration::new("example", &[code]))?;
recorder.record_lazy(|| Observation::new(
    Classification::failure(FailureCode::Logging(LoggingFailureCode::SinkWriteFailed), FailureClass::Io)
        .expect("supported catalogue pair"),
    "Producer-approved safe detail",
    std::num::NonZeroU64::MIN, // occurrence delta, never a cumulative total
))?;
let page = diagnostics.snapshot(&DiagnosticQuery::default())?;
let bounded_json: &[u8] = page.as_bytes();

Disabled contexts use the same producer calls and skip their lazy factories; reads return DiagnosticError::Disabled. Held snapshot leases use a reserved query workspace until dropped. Decoding SnapshotLease::to_snapshot instead creates an independent caller-owned DTO outside the service’s memory budget.

Re-exports

  • pub use classifiers::PluginErrorClassifier;

Modules

  • classifiers: Producer-owned pure mappings from existing typed errors to catalogue values. Pure classification for the integrated plugin-operation producer.
  • embedded: Configuration-driven service and bounded copies for embedded language runtimes. Configuration-driven embedded service and bounded language-adapter copies.

Structs

  • Classification: Shared classification payload for producers, projections, and decoded evidence.
  • ClassificationError: A cause is missing, forbidden, or unsupported by the selected catalogue code.
  • ComponentIdentity: Identity of one registered component within a diagnostic source.
  • ComponentMemoryFootprint: Assigned diagnostic storage for one component incarnation, not its heap or RSS.
  • ComponentMemoryUsage: One retained registration’s diagnostic backing.
  • ComponentMemoryView: Borrowed component row from copied query storage. Never borrows live history.
  • ComponentOwner: Restricted lifecycle capability returned only to the registration owner.
  • ComponentOwnership: Bounded attribution for a component refresh or an originating observation.
  • ComponentRecorder: Producer capability scoped to one admitted registration.
  • ComponentRegistration: Expected codes and attribution are admitted together with the summary.
  • ComponentSnapshot: One retained row per component registration instance.
  • ComponentView: Borrowed view of a component copied into a query workspace.
  • DiagnosticCapability: Capability coverage, including explicitly deferred producer integrations.
  • DiagnosticCorrelation: Optional caller correlation identifiers, excluded from aggregation keys.
  • DiagnosticCount: Magnitude of an occurrence or loss counter, including overflow visibility.
  • DiagnosticCounter: Lifetime occurrences for one code in its containing component instance.
  • DiagnosticCoverage: Explicit evidence, retention, saturation, and producer integration coverage.
  • DiagnosticCursor: Opaque continuation bound to source, capture revision, offsets, and scope.
  • DiagnosticDetail: Restricted optional recent evidence, independent of the accepted numeric summary.
  • DiagnosticDiscovery: Side-effect-free discovery, available even when snapshot queries are disabled.
  • DiagnosticEvent: One recent observation with its actual class and original configuration attribution.
  • DiagnosticLifetimeSummary: Fixed lifetime totals and monotonic timing for a context or component instance.
  • DiagnosticLimits: Independent capacities of one diagnostic context. All backing allocations are admitted during startup; these limits are not a whole-process RSS ceiling.
  • DiagnosticLoss: Source loss state reserved independently of optional evidence capacity.
  • DiagnosticMemoryPage: Bounded independent memory view; inspection neither records nor freezes history.
  • DiagnosticMemoryUsage: Backing capacity and current occupancy of one context.
  • DiagnosticNumber: Unsigned diagnostic integer serialized losslessly as a decimal string.
  • DiagnosticOrigin: Original bounded configuration attribution carried by one observation.
  • DiagnosticOutputSummary: Allowlisted operational output, constructed independently of retained detail.
  • DiagnosticProducerSupport: One finite integration entry. Support is independent of collection enablement, configured/admitted registrations, observed evidence, and read authority.
  • DiagnosticQuery: Portable bounded selection; consumers never reset or mutate evidence.
  • DiagnosticRefreshSummary: One current resettable counting period, with no retained historical summary.
  • DiagnosticRetention: Boundaries of returned retained evidence, separate from cumulative counters.
  • DiagnosticSnapshot: Read evidence from one source incarnation, using the canonical snapshot schema.
  • DiagnosticTotals: Fixed numeric accounting for one explicitly identified lifetime or refresh scope.
  • DiagnosticWindow: Fixed-resolution outcome series for the containing component instance.
  • DiagnosticWindowBucket: An aggregate bucket using component-relative elapsed time, never raw process ticks.
  • DiagnosticWindowCoverage: Actual observation interval and limitations of a fixed-bucket window.
  • Diagnostics: Independent diagnostics context with immutable startup enablement.
  • DiagnosticsReader: Read capability for one context, without recording or lifecycle authority.
  • DiagnosticsSettings: Startup-only runtime setting. Collection is compiled normally and off unless the owner enables this context explicitly.
  • EntryMemoryFootprint: Occupied backing for one retained observation; these quantities overlap.
  • EntryMemoryUsage: One retained entry, identified within the enclosing source incarnation.
  • EntryMemoryView: Borrowed retained-entry footprint from copied query storage, without its text.
  • EventView: Borrowed view of an event copied into a query workspace.
  • ExtensionClassHandle: An admitted custom cause descriptor belonging to one registered extension. Its immutable metadata is bounded and does not create another counter series.
  • ExtensionHandle: A registered extension identity. A stale handle cannot create a new code.
  • ExtensionRegistration: Extension vocabulary is scoped to a producer namespace and admitted once.
  • MemoryInspectionLease: Memory inspection holds the same bounded permit as an ordinary snapshot. Borrowed iterators refer only to the copied page; dropping releases all storage.
  • MemoryLimitEvent: One cumulative environment limit event.
  • MemorySelectionTotals: Whole-selection totals, distinct from the rows present in this page.
  • Observation: One observation. Its count is a positive input delta, never a cumulative total.
  • OriginRecorder: An operation’s bounded original configuration attribution.
  • PluginExecutionName: A plugin execution mechanism name, preserving values unknown to this reader. Typed conversion accepts only the corresponding catalogue enum.
  • PluginObservationContext: Shared plugin-operation facts for producers, projections, and decoded evidence.
  • PluginPhaseName: A plugin lifecycle phase name, preserving values unknown to this reader. Typed conversion accepts only the corresponding catalogue enum.
  • ProjectionGuard: Bounded projection subscription, or inert disabled-mode handle.
  • RecordReceipt: Accepted lifetime and current-summary update.
  • RemoteDiagnosticOrigin: Fixed-size provenance retained by an authorized ingestion adapter.
  • ResourceMemoryMeasurement: One available measurement; an absent field means not reported (unsupported or unreadable).
  • ResourceMemoryMetrics: Memory-only projection; fixed fields and eight limit slots bound all copies.
  • ResourceMemorySample: Collection identity and memory values, copied without an unbounded retained graph.
  • ResourceMemoryView: Independent resource result joined after diagnostic capture releases its lock.
  • ResourceProcessIdentity: Verified root incarnation from the same collection, never PID alone.
  • SnapshotLease: A bounded serialized page. Dropping the lease returns its workspace permit; it owns copied bytes and never pins retained history or a component lease.
  • SourceIdentity: Identity of one Relay process or explicitly owned runtime incarnation.
  • WindowSettings: Fixed-duration component outcome windows; no code/class Cartesian product.

Enums

  • BuiltinDiagnosticCode: Fixed-size canonical authoring value with one authoritative hierarchy.
  • CliFailureCode: Failures at integrated CLI operation boundaries; causes come from producers.
  • CommonPluginFailureCode: Plugin failures supported by phase-one activation recording.
  • DaemonFailureCode: Failures observed by daemon operation owners, independent of health policy.
  • DiagnosticAvailability: Availability of evidence, without applying deployment or application health.
  • DiagnosticDetailRef: Borrowed producer-approved detail. A Display source is formatted into capped storage only when the enabled recorder invokes its lazy observation factory.
  • DiagnosticDomain: Top-level owning subsystem, derived from its catalogue code.
  • DiagnosticError: Validation, admission, or availability failure, independent of operational logging.
  • DiagnosticOutcome: Observed operation outcome; severity does not imply this value.
  • DiagnosticReadReason: Stable reasons shared by canonical snapshot adapters. These are operation results, never a source health classification or a producer failure code. Include a fallback arm when matching: future releases can add reasons.
  • DiagnosticSeverity: Severity of evidence, independent of an operation’s outcome.
  • DiagnosticSummaryScope: Scope of summary and outcome-window values in a filtered response.
  • EvidenceDisposition: Evidence retention is independent of numeric acceptance.
  • FailureClass: Supported general cause, independent of health, retries, and operation outcome.
  • FailureCode: Failure event hierarchy for integrated producers.
  • LoggingFailureCode: Initial Logging failure vocabulary.
  • MemoryFieldScope: Field-level scope; snapshot scope does not relabel system/environment data.
  • NoticeCode: Bounded non-failure observations; they never acquire a failure class.
  • PluginDiagnosticFamily: Semantic family of related plugin diagnostic codes.
  • PluginExecution: Producer-authored plugin execution mechanism, excluded from counter identity.
  • PluginFailureCode: Plugin failure hierarchy for integrated producers.
  • PluginOperationFailureCode: Failures at observed dynamic-plugin operation boundaries.
  • PluginPhase: Observed plugin lifecycle phase or policy-gate context, independent of classification.
  • ProjectionError: Subscriber conversion or delivery failure after canonical acceptance.
  • RecordOutcome: Accepted collection or intentional disablement.
  • ResourceAssociation: Relationship between the diagnostic process and measured target.
  • ResourceMemoryAvailability: Availability of the latest-memory projection, independent of diagnostic reads.
  • ResourceMemoryNumber: Exact integers and finite converted decimals retain distinct numeric kinds.
  • ResourceMemoryUnit: Original unit family and canonical unit. Inspection performs no conversion.
  • ResourceSampleStream: Independent baseline series producing this sample.
  • SuccessCode: Explicit successful operations; successes do not recover or clear failures.

Constants

Traits

  • DiagnosticClassifier: Pure producer behavior: borrow original evidence and return shared classification metadata.

Functions

  • decode_diagnostic_query: Decode an optional schema selector and the shared query. Unknown selectors, duplicate fields (including nested ones), noncanonical numbers, and excessive nesting fail safely. No file lookup, service startup, or snapshot lease occurs.

Type Aliases