Struct RequestDiagnosticScope 

pub struct RequestDiagnosticScope<'a> { /* private fields */ }

Bind once to the existing established request. No empty/default constructor.

use saddle_observability::{RequestDiagnosticScope, EmergencyDiagnosticHandle};
fn missing_context(output: &EmergencyDiagnosticHandle) {
    let scope = RequestDiagnosticScope::established(output);
}

Implementations

impl<'a> RequestDiagnosticScope<'a>

pub fn unassociated_transport(output: &'a EmergencyDiagnosticHandle) -> Self

A direct transport operation has no established request. This preserves the original while marking every request fact as not established.

pub fn outbound_wire( output: &'a EmergencyDiagnosticHandle, event: &EventContext, trace_id: &str, rpc_id: &str, zone: &str, ) -> Option<Self>

Preserve validated wire association when the observer could not create a CallContext. Missing observer facts stay explicitly unavailable.

pub fn source_error_with_target<T: Serialize>( &self, error: &(dyn Error + 'static), target: &T, category: DiagnosticCategory, cause: BoundedDiagnosticCause, ) -> RequestSourceReceipt

Capture a borrowed foreign error and its caller-supplied, validated source target under this exact request projection and occurrence. Written means every original segment, including the terminator, was synchronously acknowledged by the existing emergency file writer.

pub fn source_borrowed_error_with_target<T: Serialize, E: Error>( &self, error: &E, target: &T, category: DiagnosticCategory, cause: BoundedDiagnosticCause, ) -> RequestSourceReceipt

Capture a borrowed first error before traversing its static source chain.

pub fn early( output: Option<&'a EmergencyDiagnosticHandle>, early: EarlyRequestContext, ) -> Self

Same source issuer for early and established requests. Output availability is independent of identity absence; None never skips source retention.

Examples found in repository

examples/early_request_diagnostic.rs (line 36)

fn main() {
    // Caller is at the accepted socket phase; no trace, span, request or task is
    // fabricated to satisfy a constructor. The output may genuinely be absent.
    let scope =
        RequestDiagnosticScope::early(None, EarlyRequestContext::socket_accepted("example"))
            .with_phase(DiagnosticRequestPhase::ReadingHead);
    let failure = match read_head(&mut io::empty(), &scope) {
        Err(failure) => failure,
        Ok(()) => panic!("owned empty reader must fail"),
    };
    let id = failure.source_diagnostic().id();
    let (retained, delivery) = failure.finish_boundary_retained(
        None,
        &DiagnosticOutcomeAxes {
            operation: OperationOutcome::Failed,
            ..Default::default()
        },
    );
    assert_eq!(retained.error().kind(), io::ErrorKind::UnexpectedEof);
    assert_eq!(retained.source_diagnostic().id(), id);
    assert_eq!(
        delivery.source_submission(),
        DiagnosticSubmission::OutputUnavailable
    );
    assert_eq!(
        delivery.boundary_submission(),
        DiagnosticSubmission::OutputUnavailable
    );
    // Real consumer keeps `retained` in its task/response result, not just bool.
    println!("GO: early source retained without invented identities or output");
}

pub fn with_output<'b>( self, output: Option<&'b EmergencyDiagnosticHandle>, ) -> RequestDiagnosticScope<'b>

Move the existing projection to an available/unavailable output without replacing any context. Useful when an owning task retains the handle.

pub fn reborrow(&self) -> RequestDiagnosticScope<'a>

Fixed read-only snapshot for a task’s parent/child observation sites. Copies no receipt or execution owner. Later enrichment is NOT retroactive; a join fallback can only claim facts actually retained at spawn time.

pub fn record_nonfailure( &self, axes: &DiagnosticOutcomeAxes, ) -> Result<DiagnosticSubmission, ()>

Observe an ordinary completed operation with the exact early/established projection. Technical failures still require their mandatory carrier.

pub fn with_task( self, task: DiagnosticTaskId, ) -> Result<Self, ContextBindingError<Self>>

Examples found in repository

examples/outbound_child_diagnostic.rs (line 31)

fn main() {
    let observer = Observer::with_writer(ObserverConfig::default(), std::io::sink()).unwrap();
    let (incoming, _) = observer
        .start_external_call_with_rpc(
            "shop",
            "ingress",
            "orders",
            "query",
            Some("gateway-opaque"),
            RpcCorrelationId::new("0.3").unwrap(),
        )
        .unwrap();
    let ingress_event = EventContext::new(
        RequestIdentity::new("request-7").unwrap(),
        RouteIdentity::new("/incoming").unwrap(),
        1,
    )
    .unwrap();
    let parent = RequestDiagnosticScope::output_unavailable(incoming.context(), &ingress_event)
        .with_task(DiagnosticTaskId::from_runtime_id("42").unwrap())
        .unwrap_or_else(|_| panic!("task"))
        .with_zone(DiagnosticZone::from_validated_ingress("zone-a").unwrap());

    // programming.rs generates the wire child; Boundary uses its trace/rpc plus
    // request_id/function. The adapter below does NOT generate these identities.
    let wire_trace = "gateway-opaque";
    let wire_rpc = "0.3.1";
    let request_id = "request-7";
    let function = "remote.query";
    let (root, _) = observer
        .start_external_call_with_rpc(
            "saddle",
            "zone-a",
            "profusecontract",
            "invoke",
            Some(wire_trace),
            RpcCorrelationId::new(wire_rpc).unwrap(),
        )
        .unwrap();
    let event = EventContext::new(
        RequestIdentity::new(request_id).unwrap(),
        RouteIdentity::new(function).unwrap(),
        1,
    )
    .unwrap();
    let child = parent
        .derive_outbound_child(root.context(), &event)
        .unwrap();
    let failure = child.fail(
        std::io::ErrorKind::ConnectionRefused,
        DiagnosticCategory::UnexpectedError,
        BoundedDiagnosticCause::new(
            DiagnosticStage::RequestDecode,
            DiagnosticCode::new("outbound.connect_failed").unwrap(),
        ),
    );
    let id = failure.source_diagnostic().id();
    let (retained, delivery) =
        failure.finish_boundary_retained(None, &DiagnosticOutcomeAxes::default());
    assert_eq!(retained.source_diagnostic().id(), id);
    assert_eq!(*retained.error(), std::io::ErrorKind::ConnectionRefused);
    assert_eq!(
        delivery.source_submission(),
        DiagnosticSubmission::OutputUnavailable
    );
    assert_eq!(
        delivery.boundary_submission(),
        DiagnosticSubmission::OutputUnavailable
    );
    println!("GO: Boundary-shaped child Call/Event consumed; absent output retains same failure");
}

pub fn bind_request_identity( self, request: &RequestIdentity, ) -> Result<Self, ContextBindingError<Self>>

Bind only facts actually established by the ingress owner. On conflict no partial update occurs; task/zone/scope and prior receipts stay unchanged.

pub fn bind_established( self, call: &CallContext, event: &EventContext, ) -> Result<Self, ContextBindingError<Self>>

pub fn derive_outbound_child( &self, call: &CallContext, event: &EventContext, ) -> Result<RequestDiagnosticScope<'a>, DiagnosticContextField>

Derive the actual outbound call without rewriting the inbound scope. The caller supplies Boundary’s existing child Call/Event (not invented identities). Trace and request must already be known and match exactly; RPC must be a direct parent.<decimal sequence> child and span must differ. Missing parent identity cannot establish this relationship. Request comparison uses a private exact copy, never the redacted display value. This validates diagnostic metadata, not execution/transport authority.

Examples found in repository

examples/outbound_child_diagnostic.rs (line 58)

fn main() {
    let observer = Observer::with_writer(ObserverConfig::default(), std::io::sink()).unwrap();
    let (incoming, _) = observer
        .start_external_call_with_rpc(
            "shop",
            "ingress",
            "orders",
            "query",
            Some("gateway-opaque"),
            RpcCorrelationId::new("0.3").unwrap(),
        )
        .unwrap();
    let ingress_event = EventContext::new(
        RequestIdentity::new("request-7").unwrap(),
        RouteIdentity::new("/incoming").unwrap(),
        1,
    )
    .unwrap();
    let parent = RequestDiagnosticScope::output_unavailable(incoming.context(), &ingress_event)
        .with_task(DiagnosticTaskId::from_runtime_id("42").unwrap())
        .unwrap_or_else(|_| panic!("task"))
        .with_zone(DiagnosticZone::from_validated_ingress("zone-a").unwrap());

    // programming.rs generates the wire child; Boundary uses its trace/rpc plus
    // request_id/function. The adapter below does NOT generate these identities.
    let wire_trace = "gateway-opaque";
    let wire_rpc = "0.3.1";
    let request_id = "request-7";
    let function = "remote.query";
    let (root, _) = observer
        .start_external_call_with_rpc(
            "saddle",
            "zone-a",
            "profusecontract",
            "invoke",
            Some(wire_trace),
            RpcCorrelationId::new(wire_rpc).unwrap(),
        )
        .unwrap();
    let event = EventContext::new(
        RequestIdentity::new(request_id).unwrap(),
        RouteIdentity::new(function).unwrap(),
        1,
    )
    .unwrap();
    let child = parent
        .derive_outbound_child(root.context(), &event)
        .unwrap();
    let failure = child.fail(
        std::io::ErrorKind::ConnectionRefused,
        DiagnosticCategory::UnexpectedError,
        BoundedDiagnosticCause::new(
            DiagnosticStage::RequestDecode,
            DiagnosticCode::new("outbound.connect_failed").unwrap(),
        ),
    );
    let id = failure.source_diagnostic().id();
    let (retained, delivery) =
        failure.finish_boundary_retained(None, &DiagnosticOutcomeAxes::default());
    assert_eq!(retained.source_diagnostic().id(), id);
    assert_eq!(*retained.error(), std::io::ErrorKind::ConnectionRefused);
    assert_eq!(
        delivery.source_submission(),
        DiagnosticSubmission::OutputUnavailable
    );
    assert_eq!(
        delivery.boundary_submission(),
        DiagnosticSubmission::OutputUnavailable
    );
    println!("GO: Boundary-shaped child Call/Event consumed; absent output retains same failure");
}

pub fn with_phase(self, phase: DiagnosticRequestPhase) -> Self

Advances this projection only; retained source receipts are snapshots.

Examples found in repository

examples/early_request_diagnostic.rs (line 37)

fn main() {
    // Caller is at the accepted socket phase; no trace, span, request or task is
    // fabricated to satisfy a constructor. The output may genuinely be absent.
    let scope =
        RequestDiagnosticScope::early(None, EarlyRequestContext::socket_accepted("example"))
            .with_phase(DiagnosticRequestPhase::ReadingHead);
    let failure = match read_head(&mut io::empty(), &scope) {
        Err(failure) => failure,
        Ok(()) => panic!("owned empty reader must fail"),
    };
    let id = failure.source_diagnostic().id();
    let (retained, delivery) = failure.finish_boundary_retained(
        None,
        &DiagnosticOutcomeAxes {
            operation: OperationOutcome::Failed,
            ..Default::default()
        },
    );
    assert_eq!(retained.error().kind(), io::ErrorKind::UnexpectedEof);
    assert_eq!(retained.source_diagnostic().id(), id);
    assert_eq!(
        delivery.source_submission(),
        DiagnosticSubmission::OutputUnavailable
    );
    assert_eq!(
        delivery.boundary_submission(),
        DiagnosticSubmission::OutputUnavailable
    );
    // Real consumer keeps `retained` in its task/response result, not just bool.
    println!("GO: early source retained without invented identities or output");
}

pub fn with_missing( self, field: DiagnosticContextField, reason: DiagnosticContextMissing, ) -> Self

Missing assertions cannot erase known facts. No arbitrary key/value API.

pub fn live_db_scope( output: Option<&'a EmergencyDiagnosticHandle>, projection: &DbScopeDiagnosticContext<(&CallContext, &EventContext)>, ) -> Self

Projection from a checked live request pair; no SQL-entry side effects.

pub fn with_db_operation(self, operation: DiagnosticDbOperation) -> Self

Adds only the registered DB operation; original request/scope are intact.

pub fn set_db_operation(&mut self, operation: DiagnosticDbOperation)

Advances only this scope’s next-operation projection. Previously issued receipts own a value snapshot and are never rewritten.

pub fn with_db_operation_missing(self, reason: DiagnosticContextMissing) -> Self

pub fn with_zone(self, zone: DiagnosticZone) -> Self

Source owner supplies the original accepted zone before source capture. Every subsequent source/boundary projection includes it automatically.

Examples found in repository

examples/outbound_child_diagnostic.rs (line 33)

fn main() {
    let observer = Observer::with_writer(ObserverConfig::default(), std::io::sink()).unwrap();
    let (incoming, _) = observer
        .start_external_call_with_rpc(
            "shop",
            "ingress",
            "orders",
            "query",
            Some("gateway-opaque"),
            RpcCorrelationId::new("0.3").unwrap(),
        )
        .unwrap();
    let ingress_event = EventContext::new(
        RequestIdentity::new("request-7").unwrap(),
        RouteIdentity::new("/incoming").unwrap(),
        1,
    )
    .unwrap();
    let parent = RequestDiagnosticScope::output_unavailable(incoming.context(), &ingress_event)
        .with_task(DiagnosticTaskId::from_runtime_id("42").unwrap())
        .unwrap_or_else(|_| panic!("task"))
        .with_zone(DiagnosticZone::from_validated_ingress("zone-a").unwrap());

    // programming.rs generates the wire child; Boundary uses its trace/rpc plus
    // request_id/function. The adapter below does NOT generate these identities.
    let wire_trace = "gateway-opaque";
    let wire_rpc = "0.3.1";
    let request_id = "request-7";
    let function = "remote.query";
    let (root, _) = observer
        .start_external_call_with_rpc(
            "saddle",
            "zone-a",
            "profusecontract",
            "invoke",
            Some(wire_trace),
            RpcCorrelationId::new(wire_rpc).unwrap(),
        )
        .unwrap();
    let event = EventContext::new(
        RequestIdentity::new(request_id).unwrap(),
        RouteIdentity::new(function).unwrap(),
        1,
    )
    .unwrap();
    let child = parent
        .derive_outbound_child(root.context(), &event)
        .unwrap();
    let failure = child.fail(
        std::io::ErrorKind::ConnectionRefused,
        DiagnosticCategory::UnexpectedError,
        BoundedDiagnosticCause::new(
            DiagnosticStage::RequestDecode,
            DiagnosticCode::new("outbound.connect_failed").unwrap(),
        ),
    );
    let id = failure.source_diagnostic().id();
    let (retained, delivery) =
        failure.finish_boundary_retained(None, &DiagnosticOutcomeAxes::default());
    assert_eq!(retained.source_diagnostic().id(), id);
    assert_eq!(*retained.error(), std::io::ErrorKind::ConnectionRefused);
    assert_eq!(
        delivery.source_submission(),
        DiagnosticSubmission::OutputUnavailable
    );
    assert_eq!(
        delivery.boundary_submission(),
        DiagnosticSubmission::OutputUnavailable
    );
    println!("GO: Boundary-shaped child Call/Event consumed; absent output retains same failure");
}

pub fn with_zone_missing(self, reason: DiagnosticContextMissing) -> Self

pub fn db_scope( output: &'a EmergencyDiagnosticHandle, observation: &DbScopeObservation<(Observer, CallContext, EventContext)>, ) -> Self

Takes BOTH context and scope from the same checked token, never a raw ID or a separately supplied CallContext. Borrowing leaves terminal use intact.

pub fn db_scope_output_unavailable( observation: &DbScopeObservation<(Observer, CallContext, EventContext)>, ) -> Self

pub fn established( output: &'a EmergencyDiagnosticHandle, call: &CallContext, event: &EventContext, ) -> Self

pub fn output_unavailable(call: &CallContext, event: &EventContext) -> Self

Explicit degraded route. Context is still mandatory; no successful submission or writer readiness is inferred.

Examples found in repository

examples/outbound_child_diagnostic.rs (line 30)

fn main() {
    let observer = Observer::with_writer(ObserverConfig::default(), std::io::sink()).unwrap();
    let (incoming, _) = observer
        .start_external_call_with_rpc(
            "shop",
            "ingress",
            "orders",
            "query",
            Some("gateway-opaque"),
            RpcCorrelationId::new("0.3").unwrap(),
        )
        .unwrap();
    let ingress_event = EventContext::new(
        RequestIdentity::new("request-7").unwrap(),
        RouteIdentity::new("/incoming").unwrap(),
        1,
    )
    .unwrap();
    let parent = RequestDiagnosticScope::output_unavailable(incoming.context(), &ingress_event)
        .with_task(DiagnosticTaskId::from_runtime_id("42").unwrap())
        .unwrap_or_else(|_| panic!("task"))
        .with_zone(DiagnosticZone::from_validated_ingress("zone-a").unwrap());

    // programming.rs generates the wire child; Boundary uses its trace/rpc plus
    // request_id/function. The adapter below does NOT generate these identities.
    let wire_trace = "gateway-opaque";
    let wire_rpc = "0.3.1";
    let request_id = "request-7";
    let function = "remote.query";
    let (root, _) = observer
        .start_external_call_with_rpc(
            "saddle",
            "zone-a",
            "profusecontract",
            "invoke",
            Some(wire_trace),
            RpcCorrelationId::new(wire_rpc).unwrap(),
        )
        .unwrap();
    let event = EventContext::new(
        RequestIdentity::new(request_id).unwrap(),
        RouteIdentity::new(function).unwrap(),
        1,
    )
    .unwrap();
    let child = parent
        .derive_outbound_child(root.context(), &event)
        .unwrap();
    let failure = child.fail(
        std::io::ErrorKind::ConnectionRefused,
        DiagnosticCategory::UnexpectedError,
        BoundedDiagnosticCause::new(
            DiagnosticStage::RequestDecode,
            DiagnosticCode::new("outbound.connect_failed").unwrap(),
        ),
    );
    let id = failure.source_diagnostic().id();
    let (retained, delivery) =
        failure.finish_boundary_retained(None, &DiagnosticOutcomeAxes::default());
    assert_eq!(retained.source_diagnostic().id(), id);
    assert_eq!(*retained.error(), std::io::ErrorKind::ConnectionRefused);
    assert_eq!(
        delivery.source_submission(),
        DiagnosticSubmission::OutputUnavailable
    );
    assert_eq!(
        delivery.boundary_submission(),
        DiagnosticSubmission::OutputUnavailable
    );
    println!("GO: Boundary-shaped child Call/Event consumed; absent output retains same failure");
}

pub fn ingress_deadline_bound( &self, ingress_deadline_unix_ms: i64, ) -> DiagnosticSubmission

Final bound ingress deadline; no clock reads or new identity.

pub fn capture_required( &self, diagnostic: BoundedDiagnostic, ) -> RequestSourceReceipt

Consumes existing source facts without capturing a replacement identity.

pub fn capture_existing( &self, diagnostic: Diagnostic, observer: Option<&Observer>, ) -> ExistingDiagnosticReceipt

First submission of an already captured panic/cleanup diagnostic. Moves the original carrier, never recaptures or clones its stack. observer preserves the existing main-log mirror when one is available. Uses the legacy allocating 32KiB encoder, NOT the admitted bounded path.

pub fn fail<E>( &self, error: E, category: DiagnosticCategory, cause: BoundedDiagnosticCause, ) -> FrameworkRequestFailure<E>

Capture at the real source, before exposing its error to a caller. Submission degradation never changes the source error.

Examples found in repository

examples/early_request_diagnostic.rs (line 29)

fn read_head(
    reader: &mut impl Read,
    scope: &RequestDiagnosticScope<'_>,
) -> Result<(), FrameworkRequestFailure<io::Error>> {
    reader.read_exact(&mut [0; 1]).map_err(|error| {
        let kind = match error.kind() {
            io::ErrorKind::UnexpectedEof => "io.unexpected_eof",
            io::ErrorKind::TimedOut => "io.timed_out",
            _ => "io.other",
        };
        let cause = BoundedDiagnosticCause::new(
            DiagnosticStage::RequestDecode,
            DiagnosticCode::new("request.read_failed").unwrap(),
        )
        .with_system(DiagnosticCode::new(kind).unwrap(), error.raw_os_error());
        scope.fail(error, DiagnosticCategory::UnexpectedError, cause)
    })
}

examples/outbound_child_diagnostic.rs (lines 60-67)

fn main() {
    let observer = Observer::with_writer(ObserverConfig::default(), std::io::sink()).unwrap();
    let (incoming, _) = observer
        .start_external_call_with_rpc(
            "shop",
            "ingress",
            "orders",
            "query",
            Some("gateway-opaque"),
            RpcCorrelationId::new("0.3").unwrap(),
        )
        .unwrap();
    let ingress_event = EventContext::new(
        RequestIdentity::new("request-7").unwrap(),
        RouteIdentity::new("/incoming").unwrap(),
        1,
    )
    .unwrap();
    let parent = RequestDiagnosticScope::output_unavailable(incoming.context(), &ingress_event)
        .with_task(DiagnosticTaskId::from_runtime_id("42").unwrap())
        .unwrap_or_else(|_| panic!("task"))
        .with_zone(DiagnosticZone::from_validated_ingress("zone-a").unwrap());

    // programming.rs generates the wire child; Boundary uses its trace/rpc plus
    // request_id/function. The adapter below does NOT generate these identities.
    let wire_trace = "gateway-opaque";
    let wire_rpc = "0.3.1";
    let request_id = "request-7";
    let function = "remote.query";
    let (root, _) = observer
        .start_external_call_with_rpc(
            "saddle",
            "zone-a",
            "profusecontract",
            "invoke",
            Some(wire_trace),
            RpcCorrelationId::new(wire_rpc).unwrap(),
        )
        .unwrap();
    let event = EventContext::new(
        RequestIdentity::new(request_id).unwrap(),
        RouteIdentity::new(function).unwrap(),
        1,
    )
    .unwrap();
    let child = parent
        .derive_outbound_child(root.context(), &event)
        .unwrap();
    let failure = child.fail(
        std::io::ErrorKind::ConnectionRefused,
        DiagnosticCategory::UnexpectedError,
        BoundedDiagnosticCause::new(
            DiagnosticStage::RequestDecode,
            DiagnosticCode::new("outbound.connect_failed").unwrap(),
        ),
    );
    let id = failure.source_diagnostic().id();
    let (retained, delivery) =
        failure.finish_boundary_retained(None, &DiagnosticOutcomeAxes::default());
    assert_eq!(retained.source_diagnostic().id(), id);
    assert_eq!(*retained.error(), std::io::ErrorKind::ConnectionRefused);
    assert_eq!(
        delivery.source_submission(),
        DiagnosticSubmission::OutputUnavailable
    );
    assert_eq!(
        delivery.boundary_submission(),
        DiagnosticSubmission::OutputUnavailable
    );
    println!("GO: Boundary-shaped child Call/Event consumed; absent output retains same failure");
}