Struct DiagnosticsEmitter 

pub struct DiagnosticsEmitter { /* private fields */ }

A subsystem-scoped control surface for exposing diagnostics.

A DiagnosticsEmitter is created for a single subsystem, identified by a SubsystemIdentifier, and is attached to a specific dataspace. It hides the boilerplate of interacting with the dataspace directly, while still using it under the hood so that other subsystems can subscribe to what is exposed in a decoupled, eventually consistent way.

It exposes two capabilities:

• Collectors: named, on-demand producers of artifact bytes (see register_collector), stored as persistent dataspace assertions and automatically withdrawn when the owning process exits.
• Events: abstract, point-in-time DiagnosticEvents (see emit), delivered as transient dataspace messages to any subscribers present at the time of emission.

Example

use saluki_core::diagnostic::{DiagnosticDetails, DiagnosticEvent, DiagnosticsEmitter};
use saluki_core::runtime::state::DataspaceRegistry;
use saluki_core::support::SubsystemIdentifier;

let dataspace = DataspaceRegistry::new();
let emitter = DiagnosticsEmitter::from_dataspace(
    SubsystemIdentifier::from_segments(["my-subsystem"]),
    dataspace,
);

// Expose an artifact that is produced on demand:
emitter.register_collector("state.json", || b"{}");

// Emit a point-in-time event:
emitter.emit(DiagnosticEvent::new("credentials rejected", DiagnosticDetails::InvalidApiKey));

Implementations

impl DiagnosticsEmitter

pub fn from_current( id: SubsystemIdentifier, ) -> Result<Self, DiagnosticsEmitterError>

Creates an emitter for the given subsystem, attaching to the current dataspace.

Errors

If no dataspace is available, an error is returned.

pub fn from_dataspace( id: SubsystemIdentifier, dataspace: DataspaceRegistry, ) -> Self

Creates an emitter for the given subsystem from an already-held dataspace handle.

pub fn register_collector<F, T>( &self, artifact_name: impl Into<String>, collect_fn: F, )

where F: Fn() -> T + Send + Sync + 'static, T: Into<Vec<u8>>,

Registers a collector for a given artifact.

The collector is exposed until it is explicitly removed via unregister_collector, or until the owning process exits, whichever comes first. Registering a collector with an artifact name that is already registered by this subsystem replaces the previous one.

Care should be taken when registering a collector:

• the given artifact name should be unique within the overall system, and should be generally suitable as a file name when possible (artifact names are sanitized/normalized where necessary, but may lose useful information in the process)
• the collection function (collect_fn) will be run synchronously and should return promptly, as it can delay the collection of artifacts for the whole system

pub fn unregister_collector(&self, artifact_name: impl AsRef<str>)

Removes a previously registered collector by name

Does nothing if no collector with that name is currently registered by this subsystem.

pub fn emit(&self, event: DiagnosticEvent)

Emits a diagnostic event.

Diagnostics events are transient and only delivered to active listeners.

Trait Implementations

impl Clone for DiagnosticsEmitter

fn clone(&self) -> DiagnosticsEmitter

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.