add a book page on embedded applications

book/src/SUMMARY.md

@@ -36,7 +36,8 @@
     - [Rolling files](./emitting-events/rolling-files.md)
     - [Via OTLP](./emitting-events/otlp.md)
 - [Advanced apps](./advanced-apps.md)
-    - [Instrumenting WebAssembly](./advanced-apps/web-assembly.md)
+    - [WebAssembly](./advanced-apps/web-assembly.md)
+    - [Embedded applications](./advanced-apps/embedded.md)
     - [Integrating with OpenTelemetry](./advanced-apps/integrating-with-open-telemetry.md)
     - [Setup outside of `main`](./advanced-apps/non-main-setup.md)
 - [For developers](./for-developers.md)

book/src/advanced-apps/embedded.md

@@ -0,0 +1,46 @@
+# Instrumenting embedded applications
+
+`emit` supports embedded and constrained environments, but isn't explicitly targeting them the way frameworks like [`defmt`](https://docs.rs/defmt/latest/defmt/) do.
+
+To use `emit` in an embedded environment, you'll need to disable default crate features to avoid pulling in the standard library:
+
+```toml
+[dependencies.emit]
+version = "1.0.0"
+default-features = false
+```
+
+## Configuring a static runtime
+
+`emit` abstracts everything a diagnostic pipeline needs within a [`Runtime`](../reference/architecture.md#runtimes). Using runtimes, you can customize the clock and source of randomness in environments that don't have an obvious default, or disable them when there isn't one.
+
+```rust
+// Replace these with your own implementations, or leave as `emit::Empty`
+// if they're not supported in your target environment
+type Emitter = emit::Empty;
+type Filter = emit::Empty;
+type Ctxt = emit::Empty;
+type Clock = emit::Empty;
+type Rng = emit::Empty;
+
+// Define a static runtime using the given components
+static MY_RUNTIME: emit::Runtime<Emitter, Filter, Ctxt, Clock, Rng> = emit::Runtime::build(
+    Emitter,
+    Filter,
+    Ctxt,
+    Clock,
+    Rng,
+);
+```
+
+## Using `emit!` and `#[span]`
+
+Embedded environments need to specify a runtime explicitly in the [`emit!`](https://docs.rs/emit/1.0.0/emit/macro.emit.html) or [`#[span]`](https://docs.rs/emit/1.0.0/emit/attr.span.html) macros using the `rt` [control parameter](../reference/control-parameters.md):
+
+```rust
+# static MY_RUNTIME: emit::Runtime<emit::Empty, emit::Empty, emit::Empty, emit::Empty, emit::Empty> = emit::Runtime::build(emit::Empty, emit::Empty, emit::Empty, emit::Empty, emit::Empty);
+let user = "Embedded";
+
+// Use the static runtime, `MY_RUNTIME`, defined previously
+emit::emit!(rt: MY_RUNTIME, "Hello, {user}");
+```

book/src/advanced-apps/web-assembly.md

@@ -1,3 +1,7 @@
 # Instrumenting WebAssembly
 
-You can use `emit` in WebAssembly applications. If you're targeting WASI via the `wasm32-wasi` target, you shouldn't need to do anything special to make `emit` work. If you're targeting NodeJS or the web via the `wasm32-unknown` target, you can use [`emit_web`](https://docs.rs/emit_web) to provide a clock and source of randomness. See [the crate docs](https://docs.rs/emit_web) for more details.
+You can use `emit` in WebAssembly applications.
+
+If you're targeting WASI via the `wasm32-wasi` target, you shouldn't need to do anything special to make `emit` work.
+
+If you're targeting NodeJS or the web via the `wasm32-unknown` target, you can use [`emit_web`](https://docs.rs/emit_web) to provide a clock and source of randomness. See [the crate docs](https://docs.rs/emit_web) for more details. You can also treat `wasm32-unknown` like any other embedded target. See [Instrumenting embedded applications](./embedded.md) for more details.