pezkuwichain
830dcc9bba
* docs: Add CLAUDE_RULES.md with strict rebrand protection rules - Define immutable rebrand rules that cannot be violated - Prohibit reverting rebrand for cargo check convenience - Establish checkpoint and audit trail requirements - Document correct error handling approach * refactor: Complete kurdistan-sdk to pezkuwi-sdk rebrand - Update README.md with pezkuwi-sdk branding - Replace all kurdistan-sdk URL references with pezkuwi-sdk - Replace kurdistan-tech with pezkuwichain in workflows - Update email domains from @kurdistan-tech.io to @pezkuwichain.io - Rename tool references: kurdistan-tech-publish → pezkuwi-publish - Update runner names: kurdistan-tech-* → pezkuwichain-* - Update analytics/forum/matrix domains to pezkuwichain.io - Keep 'Kurdistan Tech Institute' as organization name - Keep tech@kurdistan.gov as official government contact
2.3 KiB
pez-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.