Crate tracing_gum

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

hash_to_trace_identifier

A helper to convert the hash to the fixed size representation needed for jaeger.