From 042c0b800dee0fc664583fd3a61062e55da33d48 Mon Sep 17 00:00:00 2001 From: Marcin S Date: Thu, 25 May 2023 11:17:38 -0400 Subject: [PATCH 1/5] Document usage of gum crate --- node/gum/README.md | 4 +++ node/gum/src/lib.rs | 79 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 83 insertions(+) diff --git a/node/gum/README.md b/node/gum/README.md index 9d2cc3168cdd..739ce3066ecb 100644 --- a/node/gum/README.md +++ b/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/node/gum/src/lib.rs b/node/gum/src/lib.rs index 8e65343d21e2..43f0513c9baa 100644 --- a/node/gum/src/lib.rs +++ b/node/gum/src/lib.rs @@ -20,6 +20,85 @@ //! 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 +//! +//! Instead of `warn!` you can use one of the other available macros, which are +//! based on the [`tracing` +//! macros](https://docs.rs/tracing/latest/tracing/index.html#macros). 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::prepare-worker"; +//! ``` +//! +//! The target can be an arbitrary string, but we use the `::` syntax to mimic +//! Rust's module separators. +//! +//! ### 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`: +//! +//! ``` +//! RUST_LOG=parachain::pvf=trace cargo test +//! ``` pub use tracing::{enabled, event, Level}; From 0be1fea2aa8f6e7c938925e08af2a79d06ba5ac2 Mon Sep 17 00:00:00 2001 From: Marcin S Date: Thu, 25 May 2023 11:24:57 -0400 Subject: [PATCH 2/5] Small fix --- node/gum/src/lib.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/node/gum/src/lib.rs b/node/gum/src/lib.rs index 43f0513c9baa..587e6d6bc116 100644 --- a/node/gum/src/lib.rs +++ b/node/gum/src/lib.rs @@ -96,7 +96,7 @@ //! //! On the command line you specify `RUST_LOG`: //! -//! ``` +//! ```sh //! RUST_LOG=parachain::pvf=trace cargo test //! ``` From ea30b596b1c25539db84bd7ae7ecbde130017de7 Mon Sep 17 00:00:00 2001 From: Marcin S Date: Thu, 25 May 2023 11:28:58 -0400 Subject: [PATCH 3/5] Add some more basic info --- node/gum/src/lib.rs | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/node/gum/src/lib.rs b/node/gum/src/lib.rs index 587e6d6bc116..051331d1a6c8 100644 --- a/node/gum/src/lib.rs +++ b/node/gum/src/lib.rs @@ -94,11 +94,14 @@ //! sp_tracing::try_init_simple(); //! ``` //! -//! On the command line you specify `RUST_LOG`: +//! 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 sub-modules. pub use tracing::{enabled, event, Level}; From 71388e6e686b62d5f07d95296c4ae20e9e934895 Mon Sep 17 00:00:00 2001 From: Marcin S Date: Thu, 25 May 2023 12:08:24 -0400 Subject: [PATCH 4/5] Update node/gum/src/lib.rs Co-authored-by: Andrei Sandu <54316454+sandreim@users.noreply.github.com> --- node/gum/src/lib.rs | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/node/gum/src/lib.rs b/node/gum/src/lib.rs index 051331d1a6c8..2faed0ba2055 100644 --- a/node/gum/src/lib.rs +++ b/node/gum/src/lib.rs @@ -40,10 +40,8 @@ //! //! ### Log levels //! -//! Instead of `warn!` you can use one of the other available macros, which are -//! based on the [`tracing` -//! macros](https://docs.rs/tracing/latest/tracing/index.html#macros). In decreasing -//! order of priority they are: +//! All of the the [`tracing` macros](https://docs.rs/tracing/latest/tracing/index.html#macros) log level macros are available. +//! In decreasing order of priority they are: //! //! - `error!` //! - `warn!` From 6f3aa5386f0e9f236f13667024fcc56aac975c20 Mon Sep 17 00:00:00 2001 From: Marcin S Date: Thu, 25 May 2023 12:19:15 -0400 Subject: [PATCH 5/5] Update target docs --- node/gum/src/lib.rs | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/node/gum/src/lib.rs b/node/gum/src/lib.rs index 2faed0ba2055..c2d62d98a671 100644 --- a/node/gum/src/lib.rs +++ b/node/gum/src/lib.rs @@ -40,7 +40,7 @@ //! //! ### Log levels //! -//! All of the the [`tracing` macros](https://docs.rs/tracing/latest/tracing/index.html#macros) log level macros are available. +//! 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!` @@ -54,11 +54,14 @@ //! The `LOG_TARGET` should be defined once per crate, e.g.: //! //! ```rs -//! const LOG_TARGET: &str = "parachain::pvf::prepare-worker"; +//! const LOG_TARGET: &str = "parachain::pvf"; //! ``` //! -//! The target can be an arbitrary string, but we use the `::` syntax to mimic -//! Rust's module separators. +//! This should be of the form `::`, where the `::` 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 //! @@ -99,7 +102,7 @@ //! ``` //! //! On the other hand if you want all `parachain` logs, specify `parachain=trace`, which will also -//! include logs from `parachain::pvf` and other sub-modules. +//! include logs from `parachain::pvf` and other subtargets. pub use tracing::{enabled, event, Level};