fix(telemetry): make the consensus trace strategy an enum

consensus_trace_strategy was read as a std::string and compared against the
literal "attribute" in startRoundTracing(), while the runbook documented
"deterministic" and "random". The documented value "random" therefore fell
through to the default and did nothing.

Parse the setting once into ConsensusTraceStrategy, so the consensus code
branches on a type. The accepted spellings are now "deterministic" and
"random"; anything else fails at startup instead of silently defaulting.
The behaviour behind the old "attribute" name is unchanged and is now
reached by "random".

Document consensus_trace_strategy in xrpld-example.cfg, stating that
"random" is experimental and not used: it gives each node its own trace id,
so one round arrives as one trace per node.

Also state on the tx.included event that it covers the agreed consensus set
before the ledger is built, so it is a superset of the accepted ledger.

include/xrpl/consensus/ConsensusSpanNames.h

@@ -317,7 +317,9 @@ namespace event {
  */
 inline constexpr auto disputeResolve = join(makeStr("dispute"), makeStr("resolve"));
 /**
- * "tx.included"
+ * "tx.included" — one per transaction of the agreed consensus set, recorded
+ * before the ledger is built. A transaction that then fails to apply still
+ * has an event, so this is a superset of the accepted ledger's contents.
  */
 inline constexpr auto txIncluded = join(makeStr("tx"), makeStr("included"));
 

include/xrpl/telemetry/Telemetry.h

@@ -122,6 +122,69 @@ namespace xrpl::telemetry {
 inline constexpr std::string_view kTracerName{"xrpld"};
 #endif
 
+/**
+ * How a consensus round span picks its trace id.
+ *
+ *   consensus_trace_strategy (xrpld.cfg)
+ *          |
+ *          v
+ *   makeTelemetrySetup()  ──>  Setup::consensusTraceStrategy
+ *          |
+ *          v
+ *   RCLConsensus::Adaptor::startRoundTracing()
+ *          |
+ *          +-- Deterministic ──> SpanGuard::hashSpan(prev ledger hash)
+ *          +-- Random        ──> SpanGuard::span() / linkedSpan()
+ *
+ * Deterministic is the strategy in use. Every validator of a round hashes the
+ * same previous ledger id, so all of them land in one trace.
+ *
+ * Random is experimental and not used. Each node would invent its own trace
+ * id, so one round would arrive as one trace per node, joinable only by the
+ * `consensus_ledger_id` attribute.
+ *
+ * @code
+ * // Branch on the strategy rather than on a string.
+ * if (telemetry.getConsensusTraceStrategy() == ConsensusTraceStrategy::Random)
+ *     span = SpanGuard::span(TraceCategory::Consensus, seg::consensus, op::round);
+ * else
+ *     span = SpanGuard::hashSpan(TraceCategory::Consensus, name, id.data(), id.kBytes);
+ *
+ * // Edge case: the value also goes on a span attribute, so it needs its
+ * // config spelling back.
+ * span.setAttribute(attr::traceStrategy, strategyName(ConsensusTraceStrategy::Random));
+ * @endcode
+ *
+ * @note Adding an enumerator means adding a spelling to strategyName() below
+ * and to the parser in TelemetryConfig.cpp. Both switch without a default, so
+ * the compiler catches a missed one.
+ */
+enum class ConsensusTraceStrategy : std::uint8_t { Deterministic, Random };
+
+/**
+ * Config spelling of a consensus trace strategy.
+ *
+ * This is the same text `consensus_trace_strategy` accepts, and it is what
+ * goes on the `trace_strategy` span attribute, so the two cannot drift.
+ *
+ * @param strategy  Strategy to name.
+ * @return "deterministic" or "random", pointing at a string literal.
+ */
+[[nodiscard]] constexpr char const*
+strategyName(ConsensusTraceStrategy strategy)
+{
+    switch (strategy)
+    {
+        case ConsensusTraceStrategy::Deterministic:
+            return "deterministic";
+        case ConsensusTraceStrategy::Random:
+            return "random";
+    }
+    // The switch covers every enumerator. This return only satisfies the
+    // compiler, which cannot rule out a value outside the enumeration.
+    return "deterministic";
+}
+
 class Telemetry
 {
     /**
@@ -267,12 +330,12 @@ public:
         bool traceLedger = true;
 
         /**
-         * Strategy for cross-node consensus trace correlation.
-         * "deterministic" — derive trace_id from ledger hash so all
-         * validators in the same round share the same trace_id.
-         * "attribute" — random trace_id, correlate via ledger_id attribute.
+         * How a consensus round span picks its trace id.
+         *
+         * Read from `consensus_trace_strategy`. Deterministic is the strategy
+         * in use; Random is experimental. See ConsensusTraceStrategy.
          */
-        std::string consensusTraceStrategy = "deterministic";
+        ConsensusTraceStrategy consensusTraceStrategy = ConsensusTraceStrategy::Deterministic;
     };
 
     virtual ~Telemetry() = default;
@@ -345,9 +408,9 @@ public:
     shouldTraceLedger() const = 0;
 
     /**
-     * @return The configured consensus trace correlation strategy.
+     * @return How a consensus round span picks its trace id.
      */
-    [[nodiscard]] virtual std::string const&
+    [[nodiscard]] virtual ConsensusTraceStrategy
     getConsensusTraceStrategy() const = 0;
 
 #ifdef XRPL_ENABLE_TELEMETRY