From 945097092762320e0f4b40693892562b9f633ea6 Mon Sep 17 00:00:00 2001
From: Marcin S <marcin@realemail.net>
Date: Fri, 26 May 2023 12:59:32 -0400
Subject: [PATCH] Document usage of `gum` crate (#7294)
* Document usage of gum crate
* Small fix
* Add some more basic info
* Update node/gum/src/lib.rs
Co-authored-by: Andrei Sandu <54316454+sandreim@users.noreply.github.com>
* Update target docs
---------
Co-authored-by: Andrei Sandu <54316454+sandreim@users.noreply.github.com>
---
polkadot/node/gum/README.md | 4 ++
polkadot/node/gum/src/lib.rs | 83 ++++++++++++++++++++++++++++++++++++
2 files changed, 87 insertions(+)
diff --git a/polkadot/node/gum/README.md b/polkadot/node/gum/README.md
index 9d2cc3168cd..739ce3066ec 100644
--- a/polkadot/node/gum/README.md
+++ b/polkadot/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
diff --git a/polkadot/node/gum/src/lib.rs b/polkadot/node/gum/src/lib.rs
index 8e65343d21e..c2d62d98a67 100644
--- a/polkadot/node/gum/src/lib.rs
+++ b/polkadot/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};
--
GitLab