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
58 lines
2.3 KiB
Markdown
58 lines
2.3 KiB
Markdown
# 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:
|
|
|
|
* <https://github.com/pezkuwichain/pezkuwi-sdk/issues/153>
|
|
|
|
### 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.
|