#tracing #gum #observability #tempo #logging

tracing-gum

Stick logs together with the TraceID as provided by tempo

9 major breaking releases

new 9.0.0 Feb 26, 2024
8.0.0 Feb 13, 2024
7.0.0 Jan 23, 2024
6.0.0 Dec 12, 2023
0.0.0 Nov 21, 2022

#205 in Debugging

Download history 472/week @ 2023-11-06 502/week @ 2023-11-13 1010/week @ 2023-11-20 894/week @ 2023-11-27 521/week @ 2023-12-04 1097/week @ 2023-12-11 667/week @ 2023-12-18 363/week @ 2023-12-25 951/week @ 2024-01-01 1157/week @ 2024-01-08 763/week @ 2024-01-15 850/week @ 2024-01-22 650/week @ 2024-01-29 698/week @ 2024-02-05 1324/week @ 2024-02-12 1444/week @ 2024-02-19

4,136 downloads per month
Used in 63 crates (33 directly)

GPL-3.0-only

15KB
202 lines

tracing-gum

"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

For cross referencing spans and logs in grafana loki and tempo, a shared traceID or TraceIdentifier is required. All logs must be annotated with such meta information.

In most cases CandidateHash is the primary identifier of the jaeger::Span and hence the source from which the traceID is derived. For cases where it is not the primary identifier, a helper tag named traceID is added to those spans (out of scope, this is already present as a convenience measure).

Log lines on the other hand side, use warn!,info!,debug!,trace!,.. API provided by the tracing crate. Many of these, contain a candidate_hash, which is not equivalent to the traceID (256bits vs 128bits), and hence must be derived.

To achieve the cross ref, either all instances of candidate_hash could be added or this could be approached more systematically by providing a macro to automatically do so.

Related issues:

Decision

Adding approx. 2 lines per tracing line including a candidate_hash reference, to derive the TraceIdentifier from that, and printing that as part of the key-value section in the tracing::* macros. The visual overhead and friction and required diligence to keep the 100s of tracing::{warn!,info!,debug!,..} up is unreasonably high in the mid/long run. This is especially true, in the context of more people joining the team. Hence a proc-macro is introduced which abstracts this away, and does so automagically at the cost of one-more-proc-macro in the codebase.

Consequences

Minimal training/impact is required to name CandidateHash as candidate_hash when providing to any of the log macros (warn!, info!, etc.).

The crate has to be used throughout the entire codebase to work consistently, to disambiguate, the prefix gum:: is used.

Feature Parity with tracing::{warn!,..} is not desired. We want consistency more than anything. All currently used features are supported with gum as well.

Dependencies

~17MB
~320K SLoC