rippled/OpenTelemetryPlan/08-appendix.md

Appendix

Parent Document: OpenTelemetryPlan.md Related: Observability Backends

---

8.1 Glossary

Term	Definition
Span	A unit of work with start/end time, name, and attributes
Trace	A collection of spans representing a complete request flow
Trace ID	128-bit unique identifier for a trace
Span ID	64-bit unique identifier for a span within a trace
Context	Carrier for trace/span IDs across boundaries
Propagator	Component that injects/extracts context
Sampler	Decides which traces to record
Exporter	Sends spans to backend
Collector	Receives, processes, and forwards telemetry
OTLP	OpenTelemetry Protocol (wire format)
W3C Trace Context	Standard HTTP headers for trace propagation
Baggage	Key-value pairs propagated across service boundaries
Resource	Entity producing telemetry (service, host, etc.)
Instrumentation	Code that creates telemetry data

rippled-Specific Terms

Term	Definition
Overlay	P2P network layer managing peer connections
Consensus	XRP Ledger consensus algorithm (RCL)
Proposal	Validator's suggested transaction set for a ledger
Validation	Validator's signature on a closed ledger
HashRouter	Component for transaction deduplication
JobQueue	Thread pool for asynchronous task execution
PerfLog	Existing performance logging system in rippled
Beast Insight	Existing metrics framework in rippled

---

8.2 Span Hierarchy Visualization

flowchart TB
    subgraph trace["Trace: Transaction Lifecycle"]
        rpc["rpc.submit<br/>(entry point)"]
        validate["tx.validate"]
        relay["tx.relay<br/>(parent span)"]

        subgraph peers["Peer Spans"]
            p1["peer.send<br/>Peer A"]
            p2["peer.send<br/>Peer B"]
            p3["peer.send<br/>Peer C"]
        end

        consensus["consensus.round"]
        apply["tx.apply"]
    end

    rpc --> validate
    validate --> relay
    relay --> p1
    relay --> p2
    relay --> p3
    p1 -.->|"context propagation"| consensus
    consensus --> apply

    style trace fill:#0f172a,stroke:#020617,color:#fff
    style peers fill:#1e3a8a,stroke:#172554,color:#fff
    style rpc fill:#1d4ed8,stroke:#1e40af,color:#fff
    style validate fill:#047857,stroke:#064e3b,color:#fff
    style relay fill:#047857,stroke:#064e3b,color:#fff
    style p1 fill:#0e7490,stroke:#155e75,color:#fff
    style p2 fill:#0e7490,stroke:#155e75,color:#fff
    style p3 fill:#0e7490,stroke:#155e75,color:#fff
    style consensus fill:#fef3c7,stroke:#fde68a,color:#1e293b
    style apply fill:#047857,stroke:#064e3b,color:#fff

---

8.3 References

OpenTelemetry Resources

1. OpenTelemetry C++ SDK
2. OpenTelemetry Specification
3. OpenTelemetry Collector
4. OTLP Protocol Specification

Standards

5. W3C Trace Context
6. W3C Baggage
7. Protocol Buffers

rippled Resources

8. rippled Source Code
9. XRP Ledger Documentation
10. rippled Overlay README
11. rippled RPC README
12. rippled Consensus README

---

8.4 Version History

Version	Date	Author	Changes
1.0	2026-02-12	-	Initial implementation plan
1.1	2026-02-13	-	Refactored into modular documents

---

8.5 Document Index

Document	Description
OpenTelemetryPlan.md	Master overview and executive summary
01-architecture-analysis.md	rippled architecture and trace points
02-design-decisions.md	SDK selection, exporters, span conventions
03-implementation-strategy.md	Directory structure, performance analysis
04-code-samples.md	C++ code examples for all components
05-configuration-reference.md	rippled config, CMake, Collector configs
06-implementation-phases.md	Timeline, tasks, risks, success metrics
07-observability-backends.md	Backend selection and architecture
08-appendix.md	Glossary, references, version history

---

Previous: Observability Backends | Back to: Overview