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.

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.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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.
  • 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, independent of retention and delivery.
  • RemoteDiagnosticOrigin: Fixed-size provenance retained by an authorized ingestion adapter.
  • 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.
  • 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 separate from numeric acceptance and output delivery.
  • FailureClass: Supported general cause, independent of health, retries, and operation outcome.
  • FailureCode: Failure event hierarchy for integrated producers.
  • LoggingFailureCode: Initial Logging failure vocabulary.
  • 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 startup disablement.
  • 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.

Type Aliases