Expand description
Saddle structured logging and trace correlation.
The V1 scope is Log and Trace only; the broader name does not imply Metrics
or monitoring-platform delivery in V1. Framework components create an
Observer once and use Observer::start_external_call and
Observer::start_child_call around their async work. Records are queued
without waiting for the output writer.
Re-exports§
pub use root_diagnostic::PublicRequestFailure;pub use root_diagnostic::RequestTransactionFact;pub use root_diagnostic::RootActiveStage;pub use root_diagnostic::RootDiagnosticScope;pub use root_diagnostic::RootOutcomeFacts;pub use root_diagnostic::RootRequestEvent;pub use root_diagnostic::RootRequestFailure;pub use root_diagnostic::RootSupervisionReturn;
Modules§
- root_
diagnostic - Single-root consumer. Legacy snapshot APIs remain for not-yet-migrated domains.
Structs§
- Active
Call - An in-flight framework boundary.
- Active
Stage - Admission
Capacity Facts - Fixed observation facts, not a permit, account or second admission receipt.
- Admission
Capacity Submission - Four independent synchronous submissions, in CPU/memory/DB/outbound order. Enqueued is not written. Partial acceptance is deliberately not collapsed.
- Bottleneck
Identity - Boundary
Diagnostic Delivery - Observation only. Neither status claims that a record was written.
- Call
Context - The minimum identity propagated through Service, DB and Observability in V1.
- Capacity
Observation - Context
Binding Error - Atomic binding failure: original projection/output can be recovered unchanged.
- Diagnostic
DbOperation - Safe projection of DB’s registered static logical operation, not SQL and not registration authority. DB must supply its existing registered declaration.
- Diagnostic
IoFailure - Diagnostic
Output Snapshot - Diagnostic
Task Id - Validated read-only rendering of the existing runtime task instance ID. This does not allocate a task/sequence or prove task ownership. RP must take the digits from its real runtime ID, never a task-kind label or invented ID.
- Diagnostic
Zone - Fixed safe projection of the already accepted ingress zone. This is NOT ingress validation or routing authority; Service must pass accepted.zone.
- Domain
Event - An explicit business event associated with the current call context.
- Early
Request Context - Fixed early-request projection. It is metadata, not a second execution context, admission permission or source receipt. No trace/sequence is minted.
- Emergency
Diagnostic Handle - Emergency
Diagnostics - Startup owner: at most one independent writer per process. No join on Drop.
- Event
Context - File
Logging Config - Flush
Future - A non-blocking future returned by flush and shutdown lifecycle operations.
- Framework
Request Failure - Only the actual context-bound source submission above constructs this value.
No Clone, Default, From
, raw identity constructor, or context replacement. - Metrics
Snapshot - Allocation-free, immutable point-in-time copy of all process metrics.
- Observer
- Process-level structured logger and trace correlator.
- Observer
Config - Configuration for the bounded non-blocking logger.
- Outbound
Authority - Outbound
Observation - Reject
Reason - Request
Boundary Reference - Request
Diagnostic Scope - Bind once to the existing established request. No empty/default constructor.
- Request
Identity - Route
Identity - SpanId
- Trace
Correlation Id - TraceId
Enums§
- Admission
Construction - Construction outcome is independent of the original admission decision. Concrete error details continue through the original diagnostic mechanism.
- Admission
Construction Failure - Admission
Event Context - Borrow the original view, or report only real pre-root application/lifecycle. Neither form creates or retains a request root or task.
- Call
Kind - Framework boundaries that automatically produce start and finish records.
- Call
Outcome - Stable completion classification for framework call logs.
- Capacity
Dimension - Chain
Field Error - Database
Disposition - Diagnostic
Context Field - Closed missing-field vocabulary. This cannot inject arbitrary JSON keys.
- Diagnostic
Context Missing - Absence asserted by the component holding the real execution context. Never inferred from a missing optional string or from an endpoint.
- Diagnostic
Request Phase - Actual request phase supplied by its execution owner; not admission authority.
- Diagnostic
Shutdown - Diagnostic
Submission - Diagnostic
Zone Error - Domain
Event Error - Validation failures for bounded V1 domain events.
- Domain
Value - Scalar domain data that is safe and intentional to include in a log event.
- Emergency
Init Error - Event
Level - Stable severity values emitted by Saddle’s JSON logger.
- Flush
Error - A flush or managed shutdown result that is safe to expose to framework code.
- Health
- Inbound
Trace - How an external request’s trace identifier was selected.
- Init
Error - Lifecycle
State - Lifecycle
Timeout Stage - Outbound
Result - Output
Stage - The output operation whose first failure made log delivery unhealthy.
- Rotation
- Stage
- Stage
Outcome - Trace
IdError - The reason a textual trace identifier cannot be inherited or parsed.
- Transaction
Outcome - DB owning-driver facts, not an inference from HTTP or connection disposal.
Constants§
- EMERGENCY_
FILE_ NAME - LATENCY_
BUCKET_ UPPER_ MS - MAX_
DOMAIN_ EVENT_ NAME_ BYTES - Maximum UTF-8 byte length of a domain event name.
- MAX_
DOMAIN_ FIELDS - Maximum number of scalar fields in one domain event.
- MAX_
DOMAIN_ FIELD_ NAME_ BYTES - Maximum UTF-8 byte length of a domain field name.
- MAX_
DOMAIN_ PAYLOAD_ BYTES - Maximum encoded JSON bytes for the name and fields of one domain event.
- MAX_
DOMAIN_ STRING_ BYTES - Maximum UTF-8 byte length of one domain string value.
Functions§
- admission_
capacity_ layouts - Source temporaries only; fixed frame/queued packet are reported by the existing request_logging_layouts. Neither context form adds an allocation.
- global
- Returns the initialized process observer, if application startup installed it.
- init
- Initializes stdout logging once. Later calls return the first observer.
- init_
file - Initializes the process logger with the sole calendar-rotated file sink.
- trace_
id_ from_ hex - Parses Saddle’s fixed-width hexadecimal trace-id representation.
Type Aliases§
- Existing
Diagnostic Receipt - Request
Source Receipt - Actual source capture/submission receipt; no public construction or Clone.
- Transaction
Terminal Observation - Same-request/scope carrier checked by Core and transported by Runtime. It is consumed once; it is not proof of transaction outcome or log durability.