Document usage of gum crate

node/gum/README.md

@@ -3,6 +3,10 @@
 "gum" to make `tracing::{warn,info,..}` and `mick-jaeger` stick together, to be
 cross referenced in grafana with zero additional loc in the source code.
 
+## Usage
+
+See the crate docs (e.g. run `cargo doc --open`) for usage information!
+
 ## Architecture Decision Record (ADR)
 
 ### Context

node/gum/src/lib.rs

@@ -20,6 +20,89 @@
 
 //! A wrapper around `tracing` macros, to provide semi automatic
 //! `traceID` annotation without codebase turnover.
+//!
+//! # Usage
+//!
+//! The API follows the [`tracing`
+//! API](https://docs.rs/tracing/latest/tracing/index.html), but the docs contain
+//! more detail than you probably need to know, so here's the quick version.
+//!
+//! Most common usage is of the form:
+//!
+//! ```rs
+//! gum::warn!(
+//!     target: LOG_TARGET,
+//!     worker_pid = %idle_worker.pid,
+//!     ?error,
+//!     "failed to send a handshake to the spawned worker",
+//! );
+//! ```
+//!
+//! ### Log levels
+//!
+//! All of the the [`tracing` macros](https://docs.rs/tracing/latest/tracing/index.html#macros) are available.
+//! In decreasing order of priority they are:
+//!
+//! - `error!`
+//! - `warn!`
+//! - `info!`
+//! - `debug!`
+//! - `trace!`
+//!
+//! ### `target`
+//!
+//! The `LOG_TARGET` should be defined once per crate, e.g.:
+//!
+//! ```rs
+//! const LOG_TARGET: &str = "parachain::pvf";
+//! ```
+//!
+//! This should be of the form `<target>::<subtarget>`, where the `::<subtarget>` is optional.
+//!
+//! The target and subtarget are used when debugging by specializing the Grafana Loki query to
+//! filter specific subsystem logs. The more specific the query is the better when approaching the
+//! query response limit.
+//!
+//! ### Fields
+//!
+//! Here's the rundown on how fields work:
+//!
+//! - Fields on spans and events are specified using the `syntax field_name =
+//!   field_value`.
+//! - Local variables may be used as field values without an assignment, similar to
+//!   struct initializers.
+//! - The `?` sigil is shorthand that specifies a field should be recorded using its
+//!   `fmt::Debug` implementation.
+//! - The `%` sigil operates similarly, but indicates that the value should be
+//!   recorded using its `fmt::Display` implementation.
+//!
+//! For full details, again see [the tracing
+//! docs](https://docs.rs/tracing/latest/tracing/index.html#recording-fields).
+//!
+//! ### Viewing traces
+//!
+//! When testing,
+//!
+//! ```rs
+//! sp_tracing::init_for_tests();
+//! ```
+//!
+//! should enable all trace logs.
+//!
+//! Alternatively, you can do:
+//!
+//! ```rs
+//! sp_tracing::try_init_simple();
+//! ```
+//!
+//! On the command line you specify `RUST_LOG` with the desired target and trace level:
+//!
+//! ```sh
+//! RUST_LOG=parachain::pvf=trace cargo test
+//! ```
+//!
+//! On the other hand if you want all `parachain` logs, specify `parachain=trace`, which will also
+//! include logs from `parachain::pvf` and other subtargets.
 
 pub use tracing::{enabled, event, Level};