Phase 1b: Telemetry infrastructure — core library, build system, Docker stack

.github/scripts/levelization/results/ordering.txt

@@ -32,6 +32,8 @@ libxrpl.server > xrpl.server
 libxrpl.shamap > xrpl.basics
 libxrpl.shamap > xrpl.protocol
 libxrpl.shamap > xrpl.shamap
+libxrpl.telemetry > xrpl.basics
+libxrpl.telemetry > xrpl.telemetry
 libxrpl.tx > xrpl.basics
 libxrpl.tx > xrpl.conditions
 libxrpl.tx > xrpl.core
@@ -206,6 +208,7 @@ xrpl.server > xrpl.shamap
 xrpl.shamap > xrpl.basics
 xrpl.shamap > xrpl.nodestore
 xrpl.shamap > xrpl.protocol
+xrpl.telemetry > xrpl.basics
 xrpl.tx > xrpl.basics
 xrpl.tx > xrpl.core
 xrpl.tx > xrpl.ledger
@@ -224,6 +227,7 @@ xrpld.app > xrpl.rdb
 xrpld.app > xrpl.resource
 xrpld.app > xrpl.server
 xrpld.app > xrpl.shamap
+xrpld.app > xrpl.telemetry
 xrpld.app > xrpl.tx
 xrpld.consensus > xrpl.basics
 xrpld.consensus > xrpl.json

CMakeLists.txt

@@ -126,6 +126,18 @@ if (rocksdb)
     target_link_libraries(xrpl_libs INTERFACE RocksDB::rocksdb)
 endif ()
 
+# OpenTelemetry distributed tracing (optional).
+# When ON, links against opentelemetry-cpp and defines XRPL_ENABLE_TELEMETRY
+# so that tracing macros in TracingInstrumentation.h are compiled in.
+# When OFF (default), all tracing code compiles to no-ops with zero overhead.
+# Enable via: conan install -o telemetry=True, or cmake -Dtelemetry=ON.
+option(telemetry "Enable OpenTelemetry tracing" OFF)
+if (telemetry)
+    find_package(opentelemetry-cpp CONFIG REQUIRED)
+    add_compile_definitions(XRPL_ENABLE_TELEMETRY)
+    message(STATUS "OpenTelemetry tracing enabled")
+endif ()
+
 # Work around changes to Conan recipe for now.
 if (TARGET nudb::core)
     set(nudb nudb::core)

cfg/xrpld-example.cfg

@@ -1529,3 +1529,46 @@ validators.txt
 # set to ssl_verify to 0.
 [ssl_verify]
 1
+#-------------------------------------------------------------------------------
+#
+# 11. Telemetry (OpenTelemetry Tracing)
+#
+#-------------------------------------------------------------------------------
+#
+# Enables distributed tracing via OpenTelemetry. Requires building with
+# -DXRPL_ENABLE_TELEMETRY=ON (telemetry Conan option).
+#
+# [telemetry]
+#
+# enabled=0
+#
+#   Enable or disable telemetry at runtime. Default: 0 (disabled).
+#
+# endpoint=http://localhost:4318/v1/traces
+#
+#   The OpenTelemetry Collector endpoint (OTLP/HTTP). Default: http://localhost:4318/v1/traces.
+#
+# exporter=otlp_http
+#
+#   Exporter type: otlp_http. Default: otlp_http.
+#
+# sampling_ratio=1.0
+#
+#   Fraction of traces to sample (0.0 to 1.0). Default: 1.0 (all traces).
+#
+# trace_rpc=1
+#
+#   Enable RPC request tracing. Default: 1.
+#
+# trace_transactions=1
+#
+#   Enable transaction lifecycle tracing. Default: 1.
+#
+# trace_consensus=1
+#
+#   Enable consensus round tracing. Default: 1.
+#
+# trace_peer=0
+#
+#   Enable peer message tracing (high volume). Default: 0.
+#

cmake/XrplCore.cmake

@@ -119,6 +119,17 @@ target_link_libraries(
 add_module(xrpl tx)
 target_link_libraries(xrpl.libxrpl.tx PUBLIC xrpl.libxrpl.ledger)
 
+# Telemetry module — OpenTelemetry distributed tracing support.
+# Sources: include/xrpl/telemetry/ (headers), src/libxrpl/telemetry/ (impl).
+# When telemetry=ON, links the Conan-provided umbrella target
+# opentelemetry-cpp::opentelemetry-cpp (individual component targets like
+# ::api, ::sdk are not available in the Conan package).
+add_module(xrpl telemetry)
+target_link_libraries(xrpl.libxrpl.telemetry PUBLIC xrpl.libxrpl.basics xrpl.libxrpl.beast)
+if (telemetry)
+    target_link_libraries(xrpl.libxrpl.telemetry PUBLIC opentelemetry-cpp::opentelemetry-cpp)
+endif ()
+
 add_library(xrpl.libxrpl)
 set_target_properties(xrpl.libxrpl PROPERTIES OUTPUT_NAME xrpl)
 
@@ -144,6 +155,7 @@ target_link_modules(
     resource
     server
     shamap
+    telemetry
     tx)
 
 # All headers in libxrpl are in modules.

cmake/XrplInstall.cmake

@@ -32,6 +32,7 @@ install(TARGETS common
                 xrpl.libxrpl.resource
                 xrpl.libxrpl.server
                 xrpl.libxrpl.shamap
+                xrpl.libxrpl.telemetry
                 xrpl.libxrpl.tx
                 antithesis-sdk-cpp
         EXPORT XrplExports

conan.lock

@@ -10,10 +10,13 @@
         "rocksdb/10.5.1#4a197eca381a3e5ae8adf8cffa5aacd0%1765850186.86",
         "re2/20230301#ca3b241baec15bd31ea9187150e0b333%1765850148.103",
         "protobuf/6.32.1#f481fd276fc23a33b85a3ed1e898b693%1765850161.038",
-        "openssl/3.5.5#05a4ac5b7323f7a329b2db1391d9941f%1769599205.414",
+        "opentelemetry-cpp/1.18.0#efd9851e173f8a13b9c7d35232de8cf1%1750409186.472",
+        "openssl/3.5.5#05a4ac5b7323f7a329b2db1391d9941f%1770229825.601",
         "nudb/2.0.9#0432758a24204da08fee953ec9ea03cb%1769436073.32",
+        "nlohmann_json/3.11.3#45828be26eb619a2e04ca517bb7b828d%1701220705.259",
         "lz4/1.10.0#59fc63cac7f10fbe8e05c7e62c2f3504%1765850143.914",
         "libiconv/1.17#1e65319e945f2d31941a9d28cc13c058%1765842973.492",
+        "libcurl/8.18.0#364bc3755cb9ef84ed9a7ae9c7efc1c1%1770984390.024",
         "libbacktrace/cci.20210118#a7691bfccd8caaf66309df196790a5a1%1765842973.03",
         "libarchive/3.8.1#ffee18995c706e02bf96e7a2f7042e0d%1765850144.736",
         "jemalloc/5.3.0#e951da9cf599e956cebc117880d2d9f8%1729241615.244",
@@ -30,9 +33,15 @@
         "zlib/1.3.1#b8bc2603263cf7eccbd6e17e66b0ed76%1765850150.075",
         "strawberryperl/5.32.1.1#707032463aa0620fa17ec0d887f5fe41%1765850165.196",
         "protobuf/6.32.1#f481fd276fc23a33b85a3ed1e898b693%1765850161.038",
+        "pkgconf/2.5.1#93c2051284cba1279494a43a4fcfeae2%1757684701.089",
+        "opentelemetry-proto/1.4.0#4096a3b05916675ef9628f3ffd571f51%1732731336.11",
+        "ninja/1.13.2#c8c5dc2a52ed6e4e42a66d75b4717ceb%1764096931.974",
         "nasm/2.16.01#31e26f2ee3c4346ecd347911bd126904%1765850144.707",
         "msys2/cci.latest#eea83308ad7e9023f7318c60d5a9e6cb%1770199879.083",
+        "meson/1.10.0#60786758ea978964c24525de19603cf4%1768294926.103",
         "m4/1.4.19#70dc8bbb33e981d119d2acc0175cf381%1763158052.846",
+        "libtool/2.4.7#14e7739cc128bc1623d2ed318008e47e%1755679003.847",
+        "gnu-config/cci.20210814#466e9d4d7779e1c142443f7ea44b4284%1762363589.329",
         "cmake/4.2.0#ae0a44f44a1ef9ab68fd4b3e9a1f8671%1765850153.937",
         "cmake/3.31.10#313d16a1aa16bbdb2ca0792467214b76%1765850153.479",
         "b2/5.3.3#107c15377719889654eb9a162a673975%1765850144.355",

conanfile.py

@@ -22,6 +22,7 @@ class Xrpl(ConanFile):
         "rocksdb": [True, False],
         "shared": [True, False],
         "static": [True, False],
+        "telemetry": [True, False],
         "tests": [True, False],
         "unity": [True, False],
         "xrpld": [True, False],
@@ -54,6 +55,7 @@ class Xrpl(ConanFile):
         "rocksdb": True,
         "shared": False,
         "static": True,
+        "telemetry": True,
         "tests": False,
         "unity": False,
         "xrpld": False,
@@ -140,6 +142,10 @@ def requirements(self):
             self.requires("jemalloc/5.3.0")
         if self.options.rocksdb:
             self.requires("rocksdb/10.5.1")
+        # OpenTelemetry C++ SDK for distributed tracing (optional).
+        # Provides OTLP/HTTP exporter, batch span processor, and trace API.
+        if self.options.telemetry:
+            self.requires("opentelemetry-cpp/1.18.0")
         self.requires("xxhash/0.8.3", **transitive_headers_opt)
 
     exports_sources = (
@@ -168,6 +174,7 @@ def generate(self):
         tc.variables["rocksdb"] = self.options.rocksdb
         tc.variables["BUILD_SHARED_LIBS"] = self.options.shared
         tc.variables["static"] = self.options.static
+        tc.variables["telemetry"] = self.options.telemetry
         tc.variables["unity"] = self.options.unity
         tc.variables["xrpld"] = self.options.xrpld
         tc.generate()
@@ -220,3 +227,5 @@ def package_info(self):
         ]
         if self.options.rocksdb:
             libxrpl.requires.append("rocksdb::librocksdb")
+        if self.options.telemetry:
+            libxrpl.requires.append("opentelemetry-cpp::opentelemetry-cpp")

docker/telemetry/docker-compose.yml

@@ -0,0 +1,60 @@
+# Docker Compose stack for rippled OpenTelemetry observability.
+#
+# Provides three services for local development:
+#   - otel-collector: receives OTLP traces from rippled, batches and
+#     forwards them to Jaeger. Listens on ports 4317 (gRPC) and 4318 (HTTP).
+#   - jaeger: all-in-one tracing backend with UI on port 16686.
+#   - grafana: dashboards on port 3000, pre-configured with Jaeger datasource.
+#
+# Usage:
+#   docker compose -f docker/telemetry/docker-compose.yml up -d
+#
+# Configure rippled to export traces by adding to xrpld.cfg:
+#   [telemetry]
+#   enabled=1
+#   endpoint=http://localhost:4318/v1/traces
+
+version: "3.8"
+
+services:
+  otel-collector:
+    image: otel/opentelemetry-collector-contrib:latest
+    command: ["--config=/etc/otel-collector-config.yaml"]
+    ports:
+      - "4317:4317" # OTLP gRPC
+      - "4318:4318" # OTLP HTTP
+      - "13133:13133" # Health check
+    volumes:
+      - ./otel-collector-config.yaml:/etc/otel-collector-config.yaml:ro
+    depends_on:
+      - jaeger
+    networks:
+      - rippled-telemetry
+
+  jaeger:
+    image: jaegertracing/all-in-one:latest
+    environment:
+      - COLLECTOR_OTLP_ENABLED=true
+    ports:
+      - "16686:16686" # Jaeger UI
+      - "14250:14250" # gRPC
+    networks:
+      - rippled-telemetry
+
+  grafana:
+    image: grafana/grafana:latest
+    environment:
+      - GF_AUTH_ANONYMOUS_ENABLED=true
+      - GF_AUTH_ANONYMOUS_ORG_ROLE=Admin
+    ports:
+      - "3000:3000"
+    volumes:
+      - ./grafana/provisioning:/etc/grafana/provisioning:ro
+    depends_on:
+      - jaeger
+    networks:
+      - rippled-telemetry
+
+networks:
+  rippled-telemetry:
+    driver: bridge

docker/telemetry/grafana/provisioning/datasources/jaeger.yaml

@@ -0,0 +1,12 @@
+# Grafana datasource provisioning for the rippled telemetry stack.
+# Auto-configures Jaeger as a trace data source on Grafana startup.
+# Access Grafana at http://localhost:3000, then use Explore -> Jaeger
+# to browse rippled traces.
+
+apiVersion: 1
+
+datasources:
+  - name: Jaeger
+    type: jaeger
+    access: proxy
+    url: http://jaeger:16686

docker/telemetry/otel-collector-config.yaml

@@ -0,0 +1,33 @@
+# OpenTelemetry Collector configuration for rippled development.
+#
+# Pipeline: OTLP receiver -> batch processor -> debug exporter + Jaeger.
+# rippled sends traces via OTLP/HTTP to port 4318. The collector batches
+# them and forwards to Jaeger via OTLP/gRPC on the Docker network.
+
+receivers:
+  otlp:
+    protocols:
+      grpc:
+        endpoint: 0.0.0.0:4317
+      http:
+        endpoint: 0.0.0.0:4318
+
+processors:
+  batch:
+    timeout: 1s
+    send_batch_size: 100
+
+exporters:
+  debug:
+    verbosity: detailed
+  otlp/jaeger:
+    endpoint: jaeger:4317
+    tls:
+      insecure: true
+
+service:
+  pipelines:
+    traces:
+      receivers: [otlp]
+      processors: [batch]
+      exporters: [debug, otlp/jaeger]