mirror of
https://github.com/XRPLF/rippled.git
synced 2026-08-03 12:11:03 +00:00
docs(telemetry): update Phase2 task list to reflect actual implementation
Mark deferred tasks (2.1→Phase 3, 2.5→low priority) with rationale. Mark superseded tasks (2.2→Phase 1c SpanGuard factory). Add Task 2.7 for Grafana search filters. Update summary table with status column. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Pratik Mankawde
@@ -1,10 +1,10 @@
|
||||
# Phase 2: RPC Tracing Completion Task List
|
||||
|
||||
> **Goal**: Complete full RPC tracing coverage with W3C Trace Context propagation, unit tests, and performance validation. Build on the POC foundation to achieve production-quality RPC observability.
|
||||
> **Goal**: Complete RPC tracing coverage with unit tests, Grafana search filters, node health attributes, and config hardening. Build on the Phase 1c SpanGuard factory foundation to achieve production-quality RPC observability.
|
||||
>
|
||||
> **Scope**: W3C header extraction, TraceContext propagation utilities, unit tests for core telemetry, integration tests for RPC tracing, and performance benchmarks.
|
||||
> **Scope**: Unit tests for core telemetry, Grafana Tempo search filters, node health span attributes, config validation (`std::clamp`).
|
||||
>
|
||||
> **Branch**: `pratik/otel-phase2-rpc-tracing` (from `pratik/OpenTelemetry_and_DistributedTracing_planning`)
|
||||
> **Branch**: `pratik/otel-phase2-rpc-tracing` (from `pratik/otel-phase1c-rpc-integration`)
|
||||
|
||||
### Related Plan Documents
|
||||
|
||||
@@ -16,59 +16,23 @@
|
||||
|
||||
---
|
||||
|
||||
## Task 2.1: Implement W3C Trace Context HTTP Header Extraction
|
||||
## Task 2.1: W3C Trace Context HTTP Header Extraction
|
||||
|
||||
**Objective**: Extract `traceparent` and `tracestate` headers from incoming HTTP RPC requests so external callers can propagate their trace context into rippled.
|
||||
**Status**: DEFERRED → Phase 3
|
||||
|
||||
**What to do**:
|
||||
**Reason**: W3C context propagation (`traceparent`/`tracestate` headers) requires a consumer — in Phase 2, RPC spans are entirely local to the node. Phase 3 introduces cross-node transaction tracing via protobuf context propagation, which is the first use case for extracted trace context. Implementing it here without a consumer would be dead code.
|
||||
|
||||
- Create `include/xrpl/telemetry/TraceContextPropagator.h`:
|
||||
- `extractFromHeaders(headerGetter)` - extract W3C traceparent/tracestate from HTTP headers
|
||||
- `injectToHeaders(ctx, headerSetter)` - inject trace context into response headers
|
||||
- Use OTel's `TextMapPropagator` with `W3CTraceContextPropagator` for standards compliance
|
||||
- Only compiled when `XRPL_ENABLE_TELEMETRY` is defined
|
||||
|
||||
- Create `src/libxrpl/telemetry/TraceContextPropagator.cpp`:
|
||||
- Implement a simple `TextMapCarrier` adapter for HTTP headers
|
||||
- Use `opentelemetry::context::propagation::GlobalTextMapPropagator` for extraction/injection
|
||||
- Register the W3C propagator in `TelemetryImpl::start()`
|
||||
|
||||
- Modify `src/xrpld/rpc/detail/ServerHandler.cpp`:
|
||||
- In the HTTP request handler, extract parent context from headers before creating span
|
||||
- Pass extracted context to `startSpan()` as parent
|
||||
- Inject trace context into response headers
|
||||
|
||||
**Key new files**:
|
||||
|
||||
- `include/xrpl/telemetry/TraceContextPropagator.h`
|
||||
- `src/libxrpl/telemetry/TraceContextPropagator.cpp`
|
||||
|
||||
**Key modified files**:
|
||||
|
||||
- `src/xrpld/rpc/detail/ServerHandler.cpp`
|
||||
- `src/libxrpl/telemetry/Telemetry.cpp` (register W3C propagator)
|
||||
|
||||
**Reference**:
|
||||
|
||||
- [04-code-samples.md §4.4.2](./04-code-samples.md) — TraceContextPropagator with extractFromHeaders/injectToHeaders
|
||||
- [02-design-decisions.md §2.5](./02-design-decisions.md) — W3C Trace Context propagation design
|
||||
**Implemented in**: `pratik/otel-phase3-tx-tracing` — `TraceContextPropagator.h/.cpp`
|
||||
|
||||
---
|
||||
|
||||
## Task 2.2: Add XRPL_TRACE_PEER Macro
|
||||
## Task 2.2: Per-Category Span Creation
|
||||
|
||||
**Objective**: Add the missing peer-tracing macro for future Phase 3 use and ensure macro completeness.
|
||||
**Status**: COMPLETE (superseded by Phase 1c design)
|
||||
|
||||
**What to do**:
|
||||
**Original plan**: Add `XRPL_TRACE_PEER` and `XRPL_TRACE_LEDGER` macros.
|
||||
|
||||
- Edit `src/xrpld/telemetry/TracingInstrumentation.h`:
|
||||
- Add `XRPL_TRACE_PEER(_tel_obj_, _span_name_)` macro that checks `shouldTracePeer()`
|
||||
- Add `XRPL_TRACE_LEDGER(_tel_obj_, _span_name_)` macro (for future ledger tracing)
|
||||
- Ensure disabled variants expand to `((void)0)`
|
||||
|
||||
**Key modified file**:
|
||||
|
||||
- `src/xrpld/telemetry/TracingInstrumentation.h`
|
||||
**Actual implementation**: Phase 1c replaced all tracing macros with the `SpanGuard::span(TraceCategory, prefix, name)` factory pattern. The `TraceCategory` enum (`Rpc`, `Transactions`, `Consensus`, `Peer`, `Ledger`) serves the same conditional-creation purpose without macros. No separate task needed — the factory already supports all categories.
|
||||
|
||||
---
|
||||
|
||||
@@ -95,59 +59,41 @@
|
||||
|
||||
## Task 2.4: Unit Tests for Core Telemetry Infrastructure
|
||||
|
||||
**Status**: COMPLETE
|
||||
|
||||
**Objective**: Add unit tests for the core telemetry abstractions to validate correctness and catch regressions.
|
||||
|
||||
**What to do**:
|
||||
**Implemented**:
|
||||
|
||||
- Create `src/test/telemetry/Telemetry_test.cpp`:
|
||||
- Test NullTelemetry: verify all methods return expected no-op values
|
||||
- Test Setup defaults: verify all Setup fields have correct defaults
|
||||
- Test setup_Telemetry config parser: verify parsing of [telemetry] section
|
||||
- Test enabled/disabled factory paths
|
||||
- Test shouldTrace\* methods respect config flags
|
||||
- `src/tests/libxrpl/telemetry/TelemetryConfig.cpp`:
|
||||
- Test Setup defaults (all fields have correct initial values)
|
||||
- Test `setup_Telemetry` config parser (empty section, full section, edge cases)
|
||||
- Test `samplingRatio` clamping (values outside 0.0-1.0)
|
||||
|
||||
- Create `src/test/telemetry/SpanGuard_test.cpp`:
|
||||
- Test SpanGuard RAII lifecycle (span ends on destruction)
|
||||
- Test move constructor works correctly
|
||||
- Test setAttribute, setOk, setStatus, addEvent, recordException
|
||||
- Test context() returns valid context
|
||||
- `src/tests/libxrpl/telemetry/SpanGuardFactory.cpp`:
|
||||
- Test null guard methods are safe (setAttribute, setOk, setError, addEvent on null)
|
||||
- Test category span returns null when telemetry disabled
|
||||
- Test child/linked span null when no parent context
|
||||
- Test move construction transfers ownership
|
||||
- Test recordException safe on null guard
|
||||
- Test discard() safe on null guard
|
||||
|
||||
- Add test files to CMake build
|
||||
|
||||
**Key new files**:
|
||||
|
||||
- `src/test/telemetry/Telemetry_test.cpp`
|
||||
- `src/test/telemetry/SpanGuard_test.cpp`
|
||||
|
||||
**Reference**:
|
||||
|
||||
- [06-implementation-phases.md §6.11.1](./06-implementation-phases.md) — Phase 1 exit criteria (unit tests passing)
|
||||
- `src/tests/libxrpl/telemetry/main.cpp` — GTest runner
|
||||
- `src/tests/libxrpl/CMakeLists.txt` — test target with optional OTel linking
|
||||
|
||||
---
|
||||
|
||||
## Task 2.5: Enhance RPC Span Attributes
|
||||
|
||||
**Objective**: Add additional attributes to RPC spans per the semantic conventions defined in the plan.
|
||||
**Status**: DEFERRED (low priority)
|
||||
|
||||
**What to do**:
|
||||
**Reason**: The high-value attributes (`command`, `version`, `role`, `status`) are already set by Phase 1c. The remaining HTTP transport-level attributes (`http.method`, `net.peer.ip`, `http.status_code`) provide limited additional insight since:
|
||||
|
||||
- Edit `src/xrpld/rpc/detail/ServerHandler.cpp`:
|
||||
- Add `http.method` attribute for HTTP requests
|
||||
- Add `http.status_code` attribute for responses
|
||||
- Add `net.peer.ip` attribute for client IP (if available)
|
||||
- `http.method` is always POST for JSON-RPC
|
||||
- `net.peer.ip` is debug-level info available in logs
|
||||
- `xrpl.rpc.duration_ms` is redundant with span duration (OTel captures start/end time natively)
|
||||
|
||||
- Edit `src/xrpld/rpc/detail/RPCHandler.cpp`:
|
||||
- Add `xrpl.rpc.duration_ms` attribute on completion
|
||||
- Add error message attribute on failure: `xrpl.rpc.error_message`
|
||||
|
||||
**Key modified files**:
|
||||
|
||||
- `src/xrpld/rpc/detail/ServerHandler.cpp`
|
||||
- `src/xrpld/rpc/detail/RPCHandler.cpp`
|
||||
|
||||
**Reference**:
|
||||
|
||||
- [02-design-decisions.md §2.4.2](./02-design-decisions.md) — RPC attribute schema
|
||||
These can be added later if dashboard queries specifically need them. The node health attributes (Task 2.8) provide far more operational value and were prioritized instead.
|
||||
|
||||
---
|
||||
|
||||
@@ -217,14 +163,17 @@ This surfaces all RPCs served during a blocked period — critical for post-inci
|
||||
|
||||
## Summary
|
||||
|
||||
| Task | Description | New Files | Modified Files | Depends On |
|
||||
| ---- | ------------------------------------------- | --------- | -------------- | ---------- |
|
||||
| 2.1 | W3C Trace Context header extraction | 2 | 2 | POC |
|
||||
| 2.2 | Add XRPL_TRACE_PEER/LEDGER macros | 0 | 1 | POC |
|
||||
| 2.3 | Add shouldTraceLedger() interface method | 0 | 3 | POC |
|
||||
| 2.4 | Unit tests for core telemetry | 2 | 1 | POC |
|
||||
| 2.5 | Enhanced RPC span attributes | 0 | 2 | POC |
|
||||
| 2.6 | Build verification and performance baseline | 0 | 0 | 2.1-2.5 |
|
||||
| 2.8 | RPC span attribute enrichment (node health) | 0 | 1 | 2.5 |
|
||||
| Task | Description | Status | Notes |
|
||||
| ---- | ------------------------------------------- | ------------------- | ------------------------------------------------ |
|
||||
| 2.1 | W3C Trace Context header extraction | Deferred → Phase 3 | No consumer in Phase 2; needs cross-node tracing |
|
||||
| 2.2 | Per-category span creation | Complete (Phase 1c) | Superseded by TraceCategory enum + SpanGuard |
|
||||
| 2.3 | Add shouldTraceLedger() interface method | Complete | All 3 implementations present |
|
||||
| 2.4 | Unit tests for core telemetry | Complete | TelemetryConfig + SpanGuardFactory tests |
|
||||
| 2.5 | Enhanced RPC span attributes (HTTP-level) | Deferred | Low value; span duration covers timing natively |
|
||||
| 2.6 | Build verification and performance baseline | Complete | Verified in CI on Phase 1c |
|
||||
| 2.7 | Grafana Tempo search filters | Complete | rpc-command, rpc-status, rpc-role filters |
|
||||
| 2.8 | RPC span attribute enrichment (node health) | Complete | amendment_blocked + server_state |
|
||||
|
||||
**Parallel work**: Tasks 2.1, 2.2, 2.3 can run in parallel. Task 2.4 depends on 2.3. Task 2.5 can run in parallel with 2.4. Task 2.6 depends on all others. Task 2.8 depends on 2.5 (existing span creation must be in place).
|
||||
**Delivered in this branch**: Tasks 2.3, 2.4, 2.6, 2.7, 2.8.
|
||||
**Deferred with rationale**: Tasks 2.1 (→Phase 3), 2.5 (low priority).
|
||||
**Superseded**: Task 2.2 (Phase 1c SpanGuard factory covers this).
|
||||
|
||||
Reference in New Issue
Block a user