Phase 5: Documentation, deployment configs, integration test infrastructure

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

src/libxrpl/telemetry/Telemetry.cpp

@@ -232,6 +232,13 @@ public:
         {
             // Force flush before shutdown
             sdkProvider_->ForceFlush();
+            // TODO: sdkProvider_ is not thread-safe. This reset() races with
+            // getTracer() if any thread is still calling startSpan().
+            // Currently safe because Application::stop() shuts down
+            // serverHandler_, overlay_, and jobQueue_ before calling
+            // telemetry_->stop() — so no callers should remain. If the
+            // shutdown order ever changes, add an std::atomic<bool> stopped_
+            // flag checked in getTracer() to make this robust.
             sdkProvider_.reset();
             trace_api::Provider::SetTracerProvider(
                 opentelemetry::nostd::shared_ptr<trace_api::TracerProvider>(

src/tests/libxrpl/telemetry/TracingMacros.cpp

@@ -27,7 +27,7 @@ TEST(TracingMacros, macros_with_null_telemetry)
     }
     {
         XRPL_TRACE_CONSENSUS(*tel, "consensus.test");
-        XRPL_TRACE_SET_ATTR("xrpl.consensus.mode", "proposing");
+        XRPL_TRACE_SET_ATTR("xrpl.consensus.mode", "Proposing");
     }
     {
         XRPL_TRACE_PEER(*tel, "peer.test");

src/xrpld/app/consensus/RCLConsensus.cpp

@@ -341,7 +341,7 @@ RCLConsensus::Adaptor::onClose(
     XRPL_TRACE_CONSENSUS(app_.getTelemetry(), "consensus.ledger_close");
     XRPL_TRACE_SET_ATTR(
         "xrpl.consensus.ledger.seq", static_cast<int64_t>(ledger.ledger_->header().seq + 1));
-    XRPL_TRACE_SET_ATTR("xrpl.consensus.mode", to_string(mode).c_str());
+    XRPL_TRACE_SET_ATTR("xrpl.consensus.mode", toDisplayString(mode).c_str());
 
     bool const wrongLCL = mode == ConsensusMode::wrongLedger;
     bool const proposing = mode == ConsensusMode::proposing;
@@ -983,8 +983,8 @@ RCLConsensus::Adaptor::onModeChange(ConsensusMode before, ConsensusMode after)
     // trace backend. Each transition (e.g. observing -> proposing) appears
     // as a child of the current consensus.round span.
     XRPL_TRACE_CONSENSUS(app_.getTelemetry(), "consensus.mode_change");
-    XRPL_TRACE_SET_ATTR("xrpl.consensus.mode.old", to_string(before).c_str());
-    XRPL_TRACE_SET_ATTR("xrpl.consensus.mode.new", to_string(after).c_str());
+    XRPL_TRACE_SET_ATTR("xrpl.consensus.mode.old", toDisplayString(before).c_str());
+    XRPL_TRACE_SET_ATTR("xrpl.consensus.mode.new", toDisplayString(after).c_str());
 
     JLOG(j_.info()) << "Consensus mode change before=" << to_string(before)
                     << ", after=" << to_string(after);
@@ -1218,7 +1218,7 @@ RCLConsensus::Adaptor::startRoundTracing(RCLCxLedger const& prevLgr)
     // Set standard attributes on the round span.
     roundSpan_->setAttribute("xrpl.consensus.ledger_id", to_string(prevLgr.id()).c_str());
     roundSpan_->setAttribute("xrpl.consensus.ledger.seq", static_cast<int64_t>(prevLgr.seq() + 1));
-    roundSpan_->setAttribute("xrpl.consensus.mode", to_string(mode_.load()).c_str());
+    roundSpan_->setAttribute("xrpl.consensus.mode", toDisplayString(mode_.load()).c_str());
     roundSpan_->setAttribute("xrpl.consensus.trace_strategy", strategy.c_str());
     roundSpan_->setAttribute("xrpl.consensus.round_id", static_cast<int64_t>(prevLgr.seq() + 1));
 

src/xrpld/app/main/Application.cpp

@@ -1592,6 +1592,10 @@ ApplicationImp::run()
     ledgerCleaner_->stop();
     m_nodeStore->stop();
     perfLog_->stop();
+    // Telemetry must stop last among trace-producing components.
+    // serverHandler_, overlay_, and jobQueue_ are already stopped above,
+    // so no threads should be calling startSpan() at this point.
+    // See TODO in TelemetryImpl::stop() re: thread-safety of sdkProvider_.
     telemetry_->stop();
 
     JLOG(m_journal.info()) << "Done.";

src/xrpld/consensus/ConsensusTypes.h

@@ -66,6 +66,26 @@ to_string(ConsensusMode m)
     }
 }
 
+/// Title Case display name for telemetry attributes and dashboards.
+/// Separate from to_string() which is used in logs and must remain stable.
+inline std::string
+toDisplayString(ConsensusMode m)
+{
+    switch (m)
+    {
+        case ConsensusMode::proposing:
+            return "Proposing";
+        case ConsensusMode::observing:
+            return "Observing";
+        case ConsensusMode::wrongLedger:
+            return "Wrong Ledger";
+        case ConsensusMode::switchedLedger:
+            return "Switched Ledger";
+        default:
+            return "Unknown";
+    }
+}
+
 /** Phases of consensus for a single ledger round.
 
     @code