TracingLayer

TracingLayer logs every delivery and its outcome as tracing events, so handlers hold no logging code of their own.

It is a layer bundled with the runtime. Added to the app with RustStream::layer, it wraps every handler, those of routers included. Each delivery gives a DEBUG event when it reaches the handler and one more event when the handler settles it. An ack is logged at INFO. A nack is logged at WARN with requeue=true or requeue=false, and a delayed retry at WARN with its delay. The events go under the ruststream::dispatch target, so RUST_LOG=ruststream::dispatch=debug shows them alone. The handler runs inside a TRACE span; TracingLayer::with_target records a name on that span. The layer never changes the outcome it logs. The events need a tracing subscriber to show, such as the one Logging installs. Batch handlers are not wrapped by app layers, so their deliveries are not logged here.

Example

The handler acks an order and drops an empty one; the layer logs both outcomes.

Macros

examples/tracing_layer.rs

#[subscriber("orders")]
async fn confirm(order: &Order) -> HandlerOutcome {
    if order.quantity == 0 {
        // The layer logs this outcome as a WARN with `requeue=false`.
        return HandlerOutcome::drop();
    }
    HandlerOutcome::ack()
}

#[ruststream::app]
fn app() -> impl App {
    RustStream::new(AppInfo::new("orders", "0.1.0"))
        // Wraps every handler the app mounts, router handlers included.
        .layer(TracingLayer::default())
        .with_broker(MemoryBroker::new(), |b| {
            b.include(confirm);
        })
}

Manual

examples/manual/tracing_layer.rs

struct Confirm;

impl Handle<Order> for Confirm {
    fn handle(
        &self,
        order: &Order,
        _outs: &(),
        _ctx: &mut Context<'_>,
    ) -> impl Future<Output = Result<(), HandlerOutcome>> {
        if order.quantity == 0 {
            // The layer logs this outcome as a WARN with `requeue=false`.
            return ready(Err(HandlerOutcome::drop()));
        }
        ready(Ok(()))
    }
}

fn app() -> impl App {
    RustStream::new(AppInfo::new("orders", "0.1.0"))
        // Wraps every handler the app mounts, router handlers included.
        .layer(TracingLayer::default())
        .with_broker(MemoryBroker::new(), |b| {
            b.include(subscriber("orders", Confirm).build());
        })
}