ARCHIVE/rippled
1
0
Fork 0
mirror of https://github.com/XRPLF/rippled.git synced 2026-06-12 21:26:51 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'pratik/otel-phase1a-plan-docs' into pratik/otel-phase1b-telemetry-infra

Browse Source
This commit is contained in:
Pratik Mankawde
2026-06-11 23:16:41 +01:00
parent d5efd657ae c3ccde3e39
commit c8e5670aed
2 changed files with 37 additions and 18 deletions
Download Patch File Download Diff File Expand all files Collapse all files

27
CONTRIBUTING.md
View File

@@ -307,14 +307,25 @@ across the code, the OTel collector, Tempo, Grafana dashboards, and docs. The
constants in the `*SpanNames.h` headers are the single source of truth; every
other layer must match them. A CI check enforces this end to end.
1. Per-span unique attribute: bare field name — the span name already carries
the domain (e.g. `command`, `local`, `version` on `rpc.command` / `tx.process`).
2. Collision qualifier: `<domain>_<field>` when a bare name would collide across
domains (in the shared spanmetrics label space) or with the OTel-reserved
`status` key (e.g. `rpc_status`, `grpc_status`, `proposal_trusted`,
`validation_trusted`).
3. Shared cross-span attribute: `<domain>_<field>` underscore form
(e.g. `tx_hash`, `peer_id`, `ledger_seq`, `consensus_round`).
1. Per-span unique attribute: bare field name — allowed when the field is
recorded by a single span/workflow, so the span name already supplies the
domain (e.g. `command`, `local`, `version` on `rpc.command` / `tx.process`).
2. Shared attribute (same concept on more than one span): ONE key, reused
verbatim on every span that records it — the span name tells the occurrences
apart, so no per-emitter prefix is added. Pick the name by the field's
meaning: a property of a domain object keeps that object's bare field name
(`ledger_hash`, `ledger_seq`, `tx_hash`, `peer_id`, `full_validation`); a
field already qualified by a sub-kind keeps that qualifier on every emitter
(`proposal_trusted` on both `consensus.proposal.receive` and
`peer.proposal.receive`; `validation_trusted` likewise). Define it once in
the base `SpanNames.h` `namespace attr` block and re-export (`using`) it from
each domain header, so all emitters share the exact string.
3. Collision qualifier: `<domain>_<field>` — only when a bare name would collide
with a DIFFERENT concept in the shared spanmetrics label space, or with the
OTel-reserved `status` key (e.g. `rpc_status`, `grpc_status`,
`consensus_state`, `consensus_round`). This disambiguates distinct concepts
that share a word; it is NOT used to tag the same concept with the workflow
that emitted it — that is rule 2 (one shared name).
4. Resource attribute: dotted `xrpl.<subsystem>.<field>` — reserved ONLY for
process/network identity set once at startup (`xrpl.network.id`,
`xrpl.network.type`). Never use the dotted `xrpl.` form for span attributes.

28
OpenTelemetryPlan/02-design-decisions.md
View File

@@ -170,16 +170,24 @@ headers are the single source of truth; the collector, Tempo, the Grafana
dashboards, and the runbook all consume these exact keys, so every layer must
agree with the code. A CI check enforces this end to end.
1. **Per-span unique attribute** → bare field name. The span name already
carries the domain, so no prefix is needed (e.g. `command`, `version`,
`local` on `rpc.command`).
2. **Collision qualifier** → `<domain>_<field>` when a bare name would collide
across domains in the shared spanmetrics label space, or with the
OTel-reserved `status` key (e.g. `rpc_status`, `grpc_status`,
`proposal_trusted`, `validation_trusted`).
3. **Shared cross-span attribute** → `<domain>_<field>` underscore form, used
wherever the same field appears on more than one span (e.g. `tx_hash`,
`peer_id`, `ledger_seq`, `consensus_round`, `consensus_mode`).
1. **Per-span unique attribute** → bare field name, allowed when the field is
recorded by a single span/workflow so the span name already supplies the
domain (e.g. `command`, `version`, `local` on `rpc.command`).
2. **Shared attribute (same concept on more than one span)** → ONE key, reused
verbatim on every span that records it; the span name tells the occurrences
apart, so no per-emitter prefix is added. Name it by the field's meaning: a
property of a domain object keeps that object's bare field name (`ledger_hash`,
`ledger_seq`, `tx_hash`, `peer_id`, `full_validation`); a field already
qualified by a sub-kind keeps that qualifier on every emitter (`proposal_trusted`
on both `consensus.proposal.receive` and `peer.proposal.receive`;
`validation_trusted` likewise). Defined once in the base `SpanNames.h`
`namespace attr` block and re-exported (`using`) by each domain header.
3. **Collision qualifier** → `<domain>_<field>`, only when a bare name would
collide with a DIFFERENT concept in the shared spanmetrics label space or with
the OTel-reserved `status` key (e.g. `rpc_status`, `grpc_status`,
`consensus_state`, `consensus_round`, `consensus_mode`). This disambiguates
distinct concepts that share a word; it is NOT used to tag the same concept
with its emitting workflow — that is rule 2 (one shared name).
4. **Resource attribute** → dotted `xrpl.<subsystem>.<field>`, reserved ONLY
for process/network identity set once at startup (`xrpl.network.id`,
`xrpl.network.type`). Span attributes are never dotted in the `xrpl.` form —