From 7a854ccad2894f7ead7974e3e9edf782d3211359 Mon Sep 17 00:00:00 2001 From: Pratik Mankawde <3397372+pratikmankawde@users.noreply.github.com> Date: Wed, 13 May 2026 15:54:13 +0100 Subject: [PATCH] =?UTF-8?q?refactor(telemetry):=20simplify=20attr=20naming?= =?UTF-8?q?=20on=20phase-1c=20=E2=80=94=20drop=20xrpl..=20prefix?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Drop xrpl.rpc.* prefix from per-span attrs (command, version). - Qualify collision-prone fields: role -> rpc_role/grpc_role, status -> rpc_status/grpc_status. - Rename payload_size -> request_payload_size for cross-domain clarity. - Simplify link.type -> link_type (bare name, no join). - Update convention doc in SpanNames.h to reflect new naming rules. - Update telemetry.md doc with renamed attr keys. Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/build/telemetry.md | 10 ++++----- include/xrpl/telemetry/SpanGuard.h | 4 ++-- include/xrpl/telemetry/SpanNames.h | 11 ++++++---- src/xrpld/app/main/GrpcSpanNames.h | 16 ++++++-------- src/xrpld/rpc/detail/RPCHandler.cpp | 6 +++--- src/xrpld/rpc/detail/RpcSpanNames.h | 30 ++++++++++++-------------- src/xrpld/rpc/detail/ServerHandler.cpp | 4 ++-- 7 files changed, 40 insertions(+), 41 deletions(-) diff --git a/docs/build/telemetry.md b/docs/build/telemetry.md index e8d7fb2dd5..1e6e715353 100644 --- a/docs/build/telemetry.md +++ b/docs/build/telemetry.md @@ -185,15 +185,15 @@ Traced RPC operations produce a span hierarchy like: ``` rpc.request - └── rpc.command.server_info (xrpl.rpc.command=server_info, xrpl.rpc.status=success) + └── rpc.command.server_info (command=server_info, rpc_status=success) ``` Each span includes attributes: -- `xrpl.rpc.command` — the RPC method name -- `xrpl.rpc.version` — API version -- `xrpl.rpc.role` — `admin` or `user` -- `xrpl.rpc.status` — `success` or `error` +- `command` — the RPC method name +- `version` — API version +- `rpc_role` — `admin` or `user` +- `rpc_status` — `success` or `error` ## Running Tests diff --git a/include/xrpl/telemetry/SpanGuard.h b/include/xrpl/telemetry/SpanGuard.h index 6718052219..6489e31c3e 100644 --- a/include/xrpl/telemetry/SpanGuard.h +++ b/include/xrpl/telemetry/SpanGuard.h @@ -50,7 +50,7 @@ auto span = SpanGuard::span( TraceCategory::Rpc, rpc_span::prefix::command, "submit"); span.setAttribute(rpc_span::attr::command, "submit"); - span.setAttribute(rpc_span::attr::status, rpc_span::val::success); + span.setAttribute(rpc_span::attr::rpcStatus, rpc_span::val::success); // span ended automatically on scope exit @endcode @@ -83,7 +83,7 @@ TraceCategory::Rpc, rpc_span::prefix::rpc, "request"); if (span) { // expensive attribute computation only when active - span.setAttribute(rpc_span::attr::payloadSize, computeSize()); + span.setAttribute(rpc_span::attr::requestPayloadSize, computeSize()); } @endcode diff --git a/include/xrpl/telemetry/SpanNames.h b/include/xrpl/telemetry/SpanNames.h index 76f13c8851..3c8b6144f9 100644 --- a/include/xrpl/telemetry/SpanNames.h +++ b/include/xrpl/telemetry/SpanNames.h @@ -16,9 +16,12 @@ * concatenation support. boost::static_string is not constexpr. * StaticStr exists specifically for compile-time dot-join composition. * - * Naming conventions follow OpenTelemetry semantic conventions: - * - Attribute keys: "xrpl.." - * - Span prefixes: "[.]" + * Naming conventions (see spec 2026-05-13-span-attr-naming-design): + * - Per-span attribute keys: bare field name (span name carries the domain). + * - Collision qualifier: _ when bare name collides across + * domains or with OTel reserved `status` (e.g. rpc_status, grpc_status). + * - Resource attribute keys: xrpl.. (process-identity). + * - Span prefixes: [.]. */ #include @@ -98,7 +101,7 @@ inline constexpr auto link = makeStr("link"); namespace attr { inline constexpr auto networkId = join(join(seg::xrpl, seg::network), makeStr("id")); inline constexpr auto networkType = join(join(seg::xrpl, seg::network), makeStr("type")); -inline constexpr auto linkType = join(join(seg::xrpl, seg::link), makeStr("type")); +inline constexpr auto linkType = makeStr("link_type"); } // namespace attr // ===== Shared attribute values ============================================= diff --git a/src/xrpld/app/main/GrpcSpanNames.h b/src/xrpld/app/main/GrpcSpanNames.h index 869d5628aa..76166e86cb 100644 --- a/src/xrpld/app/main/GrpcSpanNames.h +++ b/src/xrpld/app/main/GrpcSpanNames.h @@ -11,7 +11,7 @@ * +-------------------------------------------------------+ * | grpc.request | * | CallData::process(coro) | - * | attrs: method, role, status | + * | attrs: method, grpc_role, grpc_status | * +-------------------------------------------------------+ * * Unlike the HTTP/WS RPC path, gRPC has a flat single-span structure @@ -38,14 +38,12 @@ inline constexpr auto request = makeStr("request"); // ===== Attribute keys ====================================================== namespace attr { -inline constexpr auto xrplGrpc = join(seg::xrpl, makeStr("grpc")); - -/// "xrpl.grpc.method" -inline constexpr auto method = join(xrplGrpc, makeStr("method")); -/// "xrpl.grpc.role" -inline constexpr auto role = join(xrplGrpc, makeStr("role")); -/// "xrpl.grpc.status" -inline constexpr auto status = join(xrplGrpc, makeStr("status")); +/// "method" — gRPC method name (e.g. GetLedger). +inline constexpr auto method = makeStr("method"); +/// "grpc_role" — Domain-qualified: collides with rpc_role. +inline constexpr auto grpcRole = makeStr("grpc_role"); +/// "grpc_status" — Domain-qualified: avoids OTel reserved span status. +inline constexpr auto grpcStatus = makeStr("grpc_status"); } // namespace attr // ===== Attribute values ==================================================== diff --git a/src/xrpld/rpc/detail/RPCHandler.cpp b/src/xrpld/rpc/detail/RPCHandler.cpp index dea2343f6c..c19eefec37 100644 --- a/src/xrpld/rpc/detail/RPCHandler.cpp +++ b/src/xrpld/rpc/detail/RPCHandler.cpp @@ -166,7 +166,7 @@ callMethod(JsonContext& context, Method method, std::string const& name, Object& span.setAttribute(rpc_span::attr::command, name.c_str()); span.setAttribute(rpc_span::attr::version, static_cast(context.apiVersion)); span.setAttribute( - rpc_span::attr::role, + rpc_span::attr::rpcRole, context.role == Role::ADMIN ? std::string_view(rpc_span::val::admin) : std::string_view(rpc_span::val::user)); @@ -185,7 +185,7 @@ callMethod(JsonContext& context, Method method, std::string const& name, Object& JLOG(context.j.debug()) << "RPC call " << name << " completed in " << ((end - start).count() / 1000000000.0) << "seconds"; perfLog.rpcFinish(name, curId); - span.setAttribute(rpc_span::attr::status, rpc_span::val::success); + span.setAttribute(rpc_span::attr::rpcStatus, rpc_span::val::success); return ret; } catch (std::exception& e) @@ -193,7 +193,7 @@ callMethod(JsonContext& context, Method method, std::string const& name, Object& perfLog.rpcError(name, curId); JLOG(context.j.info()) << "Caught throw: " << e.what(); span.recordException(e); - span.setAttribute(rpc_span::attr::status, rpc_span::val::error); + span.setAttribute(rpc_span::attr::rpcStatus, rpc_span::val::error); if (context.loadType == Resource::feeReferenceRPC) context.loadType = Resource::feeExceptionRPC; diff --git a/src/xrpld/rpc/detail/RpcSpanNames.h b/src/xrpld/rpc/detail/RpcSpanNames.h index 8e88f09717..c99c153f11 100644 --- a/src/xrpld/rpc/detail/RpcSpanNames.h +++ b/src/xrpld/rpc/detail/RpcSpanNames.h @@ -14,7 +14,7 @@ * auto span = SpanGuard::span( * TraceCategory::Rpc, rpc_span::prefix::command, "submit"); * span.setAttribute(rpc_span::attr::command, "submit"); - * span.setAttribute(rpc_span::attr::status, rpc_span::val::success); + * span.setAttribute(rpc_span::attr::rpcStatus, rpc_span::val::success); * @endcode * * Span hierarchy (automatic nesting via OTel thread-local context): @@ -32,7 +32,7 @@ * | | +---------------------------------------------+ | | * | | | rpc.command.{name} | | | * | | | RPC::callMethod() | | | - * | | | attrs: command, version, role, status | | | + * | | | attrs: command, version, rpc_role, rpc_status | | | * | | +---------------------------------------------+ | | * | +--------------------------------------------------+ | * +-------------------------------------------------------+ @@ -60,7 +60,7 @@ * | +--------------------------------------------------+ | * | | rpc.command.{name} | | * | | RPC::callMethod() | | - * | | attrs: command, version, role, status | | + * | | attrs: command, version, rpc_role, rpc_status | | * | +--------------------------------------------------+ | * +-------------------------------------------------------+ * @@ -88,7 +88,7 @@ * +-------------------------------------------------------+ * | grpc.request | * | CallData::process(coro) | - * | attrs: method, status | + * | attrs: method, grpc_status | * +-------------------------------------------------------+ * * Covered paths: @@ -134,18 +134,16 @@ inline constexpr auto process = makeStr("process"); // ===== Attribute keys ====================================================== namespace attr { -inline constexpr auto xrplRpc = join(seg::xrpl, seg::rpc); - -/// "xrpl.rpc.command" -inline constexpr auto command = join(xrplRpc, makeStr("command")); -/// "xrpl.rpc.version" -inline constexpr auto version = join(xrplRpc, makeStr("version")); -/// "xrpl.rpc.role" -inline constexpr auto role = join(xrplRpc, makeStr("role")); -/// "xrpl.rpc.status" -inline constexpr auto status = join(xrplRpc, makeStr("status")); -/// "xrpl.rpc.payload_size" -inline constexpr auto payloadSize = join(xrplRpc, makeStr("payload_size")); +/// "command" — RPC method name. +inline constexpr auto command = makeStr("command"); +/// "version" — api_version per request. +inline constexpr auto version = makeStr("version"); +/// "rpc_role" — admin|user. Domain-qualified: collides with grpc_role. +inline constexpr auto rpcRole = makeStr("rpc_role"); +/// "rpc_status" — success|error. Domain-qualified: avoids OTel reserved span status. +inline constexpr auto rpcStatus = makeStr("rpc_status"); +/// "request_payload_size" — bytes of inbound request payload. +inline constexpr auto requestPayloadSize = makeStr("request_payload_size"); } // namespace attr // ===== Attribute values ==================================================== diff --git a/src/xrpld/rpc/detail/ServerHandler.cpp b/src/xrpld/rpc/detail/ServerHandler.cpp index 85454e4a29..a181ec56cd 100644 --- a/src/xrpld/rpc/detail/ServerHandler.cpp +++ b/src/xrpld/rpc/detail/ServerHandler.cpp @@ -513,7 +513,7 @@ ServerHandler::processSession( JLOG(m_journal.error()) << "Exception while processing WS: " << ex.what() << "\n" << "Input JSON: " << Json::Compact{Json::Value{jv}}; span.recordException(ex); - span.setAttribute(rpc_span::attr::status, rpc_span::val::error); + span.setAttribute(rpc_span::attr::rpcStatus, rpc_span::val::error); // LCOV_EXCL_STOP } @@ -904,7 +904,7 @@ ServerHandler::processRequest( << "Internal error : " << ex.what() << " when processing request: " << Json::Compact{Json::Value{params}}; span.recordException(ex); - span.setAttribute(rpc_span::attr::status, rpc_span::val::error); + span.setAttribute(rpc_span::attr::rpcStatus, rpc_span::val::error); // LCOV_EXCL_STOP }