ruststream 0.4.0

Async messaging framework for Rust: broker-agnostic traits, router, codecs, and a conformance harness for broker authors.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59

# Logging

RustStream emits structured [`tracing`](https://docs.rs/tracing) events throughout dispatch,
publishing, and the service lifecycle. Like any well-behaved library it installs no subscriber on its
own - that choice belongs to the application. The `logging` feature is the batteries-included answer:
a colored console subscriber driven by `RUST_LOG`.

This is separate from the [`TracingLayer`](middleware.md#built-in-layers) middleware. `TracingLayer`
*emits* an event per message; the `logging` feature installs a subscriber that *renders* events
(RustStream's own and yours) to the terminal. Use them together to see per-message logs.

## With the generated CLI

When the `logging` feature is enabled, the `#[ruststream::app]` CLI calls the logger for you on the
`run` command, so a scaffolded service logs out of the box:

```toml
ruststream = { version = "0.4", features = ["macros", "memory", "json", "logging"] }
```

```bash
RUST_LOG=ruststream=debug,info cargo run -- run
```

Output goes to **stderr** (keeping stdout clean for `asyncapi gen`), with colors enabled
automatically when stderr is a terminal.

## By hand

Install the default logger once, early in `main`:

<!-- inline-rust: manual logger-init fragment; the shipped logging example uses the automatic #[ruststream::app] installer, so there is no compiled call site for the by-hand path -->
```rust
ruststream::logging::init()?;
tracing::info!("service starting");
```

`init` reads the filter from `RUST_LOG`, falling back to `info`. Tune the defaults through the
`Logging` builder:

<!-- inline-rust: manual Logging-builder fragment; the by-hand init path has no compiled call site (the logging example uses the automatic installer) -->
```rust
use ruststream::logging::Logging;

Logging::new()
    .with_default_filter("ruststream=debug,info")  // used when RUST_LOG is unset
    .with_target(false)                            // hide the event target column
    .try_init()?;
```

`init` / `try_init` never replace an existing subscriber: a second call (or one after another crate
installed a subscriber) returns `LoggingInitError::AlreadyInitialized` rather than panicking.

## Bring your own subscriber

The `logging` feature is optional sugar. Because RustStream only emits `tracing` events, any
subscriber works - install `tracing-subscriber`, `tracing-bunyan-formatter`, an OpenTelemetry layer,
or whatever your stack uses, and the same events flow through it. Skip the `logging` feature when you
do.