merge: bring telemetry config and doc fixes forward from phase1b-telemetry-infra

OpenTelemetryPlan/05-configuration-reference.md

@@ -51,7 +51,7 @@ phases. They will be added as the corresponding subsystems are instrumented:
 
 > **TxQ** = Transaction Queue
 
-The parser `setup_Telemetry()` in `src/libxrpl/telemetry/TelemetryConfig.cpp` reads the `[telemetry]` `Section` and populates a `Telemetry::Setup` struct, applying the defaults listed in Section 5.1.2 via `section.value_or(...)`. It derives `serviceInstanceId` from the node public key when not overridden, selects the exporter endpoint default by exporter type, and leaves the sampling ratio at its fixed 1.0 default (not read from config — see Section 7.4.2).
+The parser `makeTelemetrySetup()` in `src/libxrpl/telemetry/TelemetryConfig.cpp` reads the `[telemetry]` `Section` and populates a `Telemetry::Setup` struct, applying the defaults listed in Section 5.1.2 via `section.valueOr(...)`. It derives `serviceInstanceId` from the node public key when not overridden, selects the exporter endpoint default by exporter type, and leaves the sampling ratio at its fixed 1.0 default (not read from config — see Section 7.4.2).
 
 ---
 
@@ -65,7 +65,7 @@ The parser `setup_Telemetry()` in `src/libxrpl/telemetry/TelemetryConfig.cpp` re
 > constructed with an empty `serviceInstanceId` and patched via
 > `setServiceInstanceId()` once `setup()` has called `getNodeIdentity()`.
 
-`ApplicationImp` (in `src/xrpld/app/main/Application.cpp`) owns a `std::unique_ptr<telemetry::Telemetry> telemetry_`. It is built in the member initializer list via `make_Telemetry(setup_Telemetry(...))` with an empty `serviceInstanceId`, then patched in `setup()` by calling `setServiceInstanceId()` with the Base58 node public key (unless the user supplied a custom `service_instance_id`). `start()` and `run()` forward to `telemetry_->start()` / `telemetry_->stop()`, and `getTelemetry()` returns the owned instance.
+`ApplicationImp` (in `src/xrpld/app/main/Application.cpp`) owns a `std::unique_ptr<telemetry::Telemetry> telemetry_`. It is built in the member initializer list via `makeTelemetry(makeTelemetrySetup(...))` with an empty `serviceInstanceId`, then patched in `setup()` by calling `setServiceInstanceId()` with the Base58 node public key (unless the user supplied a custom `service_instance_id`). `start()` and `run()` forward to `telemetry_->start()` / `telemetry_->stop()`, and `getTelemetry()` returns the owned instance.
 
 ### 5.3.2 ServiceRegistry Interface Addition
 
@@ -129,8 +129,8 @@ flowchart TB
     end
 
     subgraph init["Initialization"]
-        parse["setup_Telemetry()"]
-        factory["make_Telemetry()"]
+        parse["makeTelemetrySetup()"]
+        factory["makeTelemetry()"]
     end
 
     subgraph runtime["Runtime Components"]
@@ -163,7 +163,7 @@ flowchart TB
 **Reading the diagram:**
 
 - **Configuration Sources**: `xrpld.cfg` provides runtime settings (endpoint, per-component trace toggles) while the CMake flag controls whether telemetry is compiled in at all. Head sampling is fixed at 1.0 and is not a config option; volume reduction happens via tail sampling in the collector.
-- **Initialization**: `setup_Telemetry()` parses config values, then `make_Telemetry()` constructs the provider, processor, and exporter objects.
+- **Initialization**: `makeTelemetrySetup()` parses config values, then `makeTelemetry()` constructs the provider, processor, and exporter objects.
 - **Runtime Components**: The `TracerProvider` creates spans, the `BatchProcessor` buffers them, and the `OTLP Exporter` serializes and sends them over the wire.
 - **OTLP arrow to Collector**: Trace data leaves the xrpld process via OTLP/HTTP and enters the external Collector pipeline. (OTLP/gRPC is future work — see design decisions §2.2.2.)
 - **Collector Pipeline**: `Receivers` ingest OTLP data, `Processors` apply sampling/filtering/enrichment, and `Exporters` forward traces to storage backends (Tempo, etc.).

cfg/xrpld-example.cfg

@@ -1704,10 +1704,22 @@ validators.txt
 #   The node's network ID (from [network_id]) is automatically added
 #   as the `xrpl.network.id` and `xrpl.network.type` resource attributes.
 #
-# endpoint=http://localhost:4318/v1/traces
+# service_instance_id=n9KabcDEF...
 #
-#   The OTLP/HTTP exporter endpoint. The server sends trace data as
-#   protobuf-encoded HTTP POST requests to this URL.
+#   OTel resource attribute `service.instance.id`, which tells one node's
+#   telemetry apart from another's. Normally left unset: the node identity
+#   is not known when telemetry is constructed, so the server fills this in
+#   with its own Base58 node public key later during startup. Set it only
+#   to pin a stable instance name of your own choosing; doing so suppresses
+#   the node-public-key fallback.
+#   Default: the node's Base58 public key.
+#
+# traces_endpoint=http://localhost:4318/v1/traces
+#
+#   The OTLP/HTTP endpoint spans are exported to. The server sends trace
+#   data as protobuf-encoded HTTP POST requests to this URL. The full URL
+#   including the signal path is used verbatim; no other endpoint is
+#   derived from it.
 #   Default: http://localhost:4318/v1/traces.
 #
 #   Head sampling is intentionally fixed at 1.0 (sample everything) and is
@@ -1718,6 +1730,41 @@ validators.txt
 #   via tail sampling instead; for node-local post-hoc dropping use
 #   SpanGuard::discard() in code.
 #
+# use_tls=0
+#
+#   Whether to hand tls_ca_cert to the exporter as its CA bundle. TLS is
+#   selected by the scheme of traces_endpoint, not by this key; setting it
+#   to 1 only supplies a custom CA file for verifying the collector.
+#   Default: 0 (no CA file is passed, so the exporter keeps its own
+#   default trust store).
+#
+# tls_ca_cert=/etc/ssl/certs/otel-collector-ca.pem
+#
+#   Path to a PEM CA bundle used to verify the collector's certificate.
+#   Read only when use_tls=1, and passed to the exporter unchanged. The
+#   path is not checked while the config is parsed, so a missing or
+#   unreadable file surfaces as an export failure at runtime rather than
+#   as a startup error.
+#   Default: empty (no CA file).
+#
+# batch_size=512
+#
+#   Maximum number of spans in one export request. A batch is sent once
+#   this many spans have queued up, or once batch_delay_ms has elapsed,
+#   whichever happens first. Default: 512.
+#
+# batch_delay_ms=5000
+#
+#   Longest a queued span waits before its batch is exported, in
+#   milliseconds. Lower it for fresher traces at the cost of more
+#   export requests. Default: 5000 (5 seconds).
+#
+# max_queue_size=2048
+#
+#   Maximum number of spans held in memory awaiting export. Spans are
+#   dropped once the queue is full, so raise this if the collector is
+#   slow or briefly unreachable. Default: 2048.
+#
 # trace_rpc=1
 #
 #   Enable tracing for JSON-RPC and WebSocket API request handling —