Phase 1c: RPC telemetry integration — tracing macros, handler instrumentation

[pratikmankawde]

PR Chain: #6436 → #6437 → #6438 (this PR) → #6424 → #6425 → #6426 → #6427 → #6433 / #6439
Base: pratik/otel-phase1b-telemetry-infra

High Level Overview of Change

Instrument the RPC request handling layer with OpenTelemetry trace spans. Adds convenience macros for zero-overhead conditional tracing and wires them into RPCHandler and ServerHandler.

Stacked PR chain: PR #6436 (Phase 1a) → PR #6437 (Phase 1b) → Phase 1c (this) → PR #6424 → PR #6425 → PR #6426 → PR #6427

Context of Change

Phase 1c of the OpenTelemetry distributed tracing project. With the telemetry infrastructure in place (Phase 1b), this PR adds the instrumentation layer that creates trace spans for RPC operations.

The approach uses preprocessor macros (XRPL_TRACE_RPC, XRPL_TRACE_SET_ATTR, XRPL_TRACE_EXCEPTION) that expand to RAII SpanGuard objects when XRPL_ENABLE_TELEMETRY is defined, and to ((void)0) otherwise — zero runtime cost when telemetry is off.

The macro design also provides XRPL_TRACE_TX, XRPL_TRACE_CONSENSUS, and XRPL_TRACE_SPAN variants for future instrumentation phases.

Type of Change

• New feature (non-breaking change which adds functionality)

API Impact

• libxrpl change (any change that may affect libxrpl or dependents of libxrpl)

Before / After

Before: RPC requests have no tracing visibility beyond PerfLog timing.

After: Each RPC request generates trace spans with:

• ServerHandler::onRequest() → span rpc.request
• ServerHandler::processSession() → span rpc.ws_message
• ServerHandler::processRequest() → span rpc.process
• callMethod() → span rpc.command.<method> with attributes:
  • xrpl.rpc.command — method name
  • xrpl.rpc.version — API version
  • xrpl.rpc.role — admin/user
  • xrpl.rpc.status — success/error
  • Exception recording on errors

Future Tasks

• Phase 2 (PR Phase 2: Complete RPC tracing — interface, macros, attributes, tests #6424): Extended RPC tracing with tests
• Phase 3+: Transaction tracing, consensus tracing, dashboards

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 79.7%. Comparing base (252a4bb) to head (b5fb71c).

Additional details and impacted files

@@                          Coverage Diff                          @@
##           pratik/otel-phase1b-telemetry-infra   #6438     +/-   ##
=====================================================================
- Coverage                                 79.7%   79.7%   -0.0%     
=====================================================================
  Files                                      851     852      +1     
  Lines                                    67872   67895     +23     
  Branches                                  7589    7587      -2     
=====================================================================
+ Hits                                     54096   54114     +18     
- Misses                                   13776   13781      +5     

Files with missing lines	Coverage Δ
src/xrpld/rpc/detail/RPCHandler.cpp	92.0% <100.0%> (+0.8%)	⬆️
src/xrpld/rpc/detail/ServerHandler.cpp	87.8% <100.0%> (+0.1%)	⬆️

... and 5 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.