11 major breaking releases
11.0.0 | Apr 8, 2024 |
---|---|
10.0.0 | Mar 18, 2024 |
9.0.0 | Feb 26, 2024 |
8.0.0 | Feb 13, 2024 |
0.0.0 |
|
#164 in Debugging
4,461 downloads per month
Used in 64 crates
(33 directly)
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
~21MB
~440K SLoC