Crate tracing_gum

source ·
Expand description

A wrapper around tracing macros, to provide semi automatic traceID annotation without codebase turnover.

§Usage

The API follows the tracing API, 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:

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 tracing 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.:

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.

§Viewing traces

When testing,

sp_tracing::init_for_tests();

should enable all trace logs.

Alternatively, you can do:

sp_tracing::try_init_simple();

On the command line you specify RUST_LOG with the desired target and trace level:

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.

Modules§

  • event
    Events represent single points in time during the execution of a program.

Macros§

  • debug
    Print a debug level message.
  • enabled
    Checks whether a span or event is enabled based on the provided metadata.
  • error
    Print an error message.
  • event
    Constructs a new Event.
  • info
    Print a info level message.
  • trace
    Print a trace level message.
  • warn
    Print a warning level message.
  • warn_if_frequent
    Print a warning or debug level message depending on their frequency

Structs§

  • Freq
    Utility struct to compare the rate of its own calls.
  • Level
    Describes the level of verbosity of a span or event.

Enums§

  • Times
    Represents frequency per second, minute, hour and day

Functions§