From 895e9167b044ba0bd501cd3aa6ff3cb8e0f4e809 Mon Sep 17 00:00:00 2001 From: Pratik Mankawde <3397372+pratikmankawde@users.noreply.github.com> Date: Mon, 20 Apr 2026 14:29:32 +0100 Subject: [PATCH] docs(telemetry): replace text hierarchy with ASCII box diagrams Follow project convention (PerfLog.h, SpanGuard.h) for documentation diagrams. Show HTTP single, HTTP batch, and WebSocket span nesting. Co-Authored-By: Claude Opus 4.6 (1M context) --- src/xrpld/rpc/detail/RpcSpanNames.h | 58 +++++++++++++++++++++++------ 1 file changed, 47 insertions(+), 11 deletions(-) diff --git a/src/xrpld/rpc/detail/RpcSpanNames.h b/src/xrpld/rpc/detail/RpcSpanNames.h index 9f1c039254..40866ac720 100644 --- a/src/xrpld/rpc/detail/RpcSpanNames.h +++ b/src/xrpld/rpc/detail/RpcSpanNames.h @@ -19,14 +19,50 @@ * * 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] + * HTTP JSON-RPC path (single request): * - * WebSocket path: - * rpc.ws_message ServerHandler::processSession(WSSession) - * rpc.command.{name} RPC::callMethod() + * +-------------------------------------------------------+ + * | rpc.http_request | + * | ServerHandler::processSession(Session) | + * | | + * | +--------------------------------------------------+ | + * | | rpc.process | | + * | | ServerHandler::processRequest() | | + * | | | | + * | | +---------------------------------------------+ | | + * | | | rpc.command.{name} | | | + * | | | RPC::callMethod() | | | + * | | | attrs: command, version, role, status | | | + * | | +---------------------------------------------+ | | + * | +--------------------------------------------------+ | + * +-------------------------------------------------------+ + * + * HTTP batch path (multiple commands per request): + * + * +-------------------------------------------------------+ + * | rpc.http_request | + * | | + * | +--------------------------------------------------+ | + * | | rpc.process | | + * | | | | + * | | +------------------+ +------------------+ | | + * | | | rpc.command.{a} | | rpc.command.{b} | ... | | + * | | +------------------+ +------------------+ | | + * | +--------------------------------------------------+ | + * +-------------------------------------------------------+ + * + * WebSocket path: + * + * +-------------------------------------------------------+ + * | rpc.ws_message | + * | ServerHandler::processSession(WSSession) | + * | | + * | +--------------------------------------------------+ | + * | | rpc.command.{name} | | + * | | RPC::callMethod() | | + * | | attrs: command, version, role, status | | + * | +--------------------------------------------------+ | + * +-------------------------------------------------------+ * * Covered paths: * - HTTP JSON-RPC (single and batch requests) @@ -37,10 +73,10 @@ * * 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) + * - 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)