From d15d2d2df6aae632dc527b597d9e994a802741ac Mon Sep 17 00:00:00 2001 From: Pratik Mankawde <3397372+pratikmankawde@users.noreply.github.com> Date: Mon, 20 Apr 2026 14:26:55 +0100 Subject: [PATCH] docs(telemetry): add RPC span coverage map to RpcSpanNames.h Document the span hierarchy, covered paths, and known instrumentation gaps directly in the header that developers reference when adding spans. Co-Authored-By: Claude Opus 4.6 (1M context) --- src/xrpld/rpc/detail/RpcSpanNames.h | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/src/xrpld/rpc/detail/RpcSpanNames.h b/src/xrpld/rpc/detail/RpcSpanNames.h index a10fd1af3e..9f1c039254 100644 --- a/src/xrpld/rpc/detail/RpcSpanNames.h +++ b/src/xrpld/rpc/detail/RpcSpanNames.h @@ -16,6 +16,34 @@ * span.setAttribute(rpc_span::attr::command, "submit"); * span.setAttribute(rpc_span::attr::status, rpc_span::val::success); * @endcode + * + * Span hierarchy (automatic nesting via OTel thread-local context): + * + * HTTP path: + * rpc.http_request ServerHandler::processSession(Session) + * rpc.process ServerHandler::processRequest() + * rpc.command.{name} RPC::callMethod() [repeats for batch] + * + * WebSocket path: + * rpc.ws_message ServerHandler::processSession(WSSession) + * rpc.command.{name} RPC::callMethod() + * + * Covered paths: + * - HTTP JSON-RPC (single and batch requests) + * - WebSocket RPC commands + * - Admin CLI (connects via HTTP internally) + * - Command execution: timing, success/failure, exceptions + * - Per-command attributes: name, API version, role, status + * + * Known gaps (not yet instrumented): + * - gRPC endpoints (GRPCServer.cpp) — no spans at all + * - Early validation errors in processRequest() before rpc.process span + * (malformed JSON, auth failures, oversized requests) + * - fillHandler() rejections in doCommand() before rpc.command span + * (unknown command, too busy, permission denied) + * - WebSocket upgrade failures in onHandoff() + * - WebSocket message parse errors in onWSMessage() + * - Subscription push notifications (server-initiated, not RPC) */ #include