diff --git a/OpenTelemetryPlan/05-configuration-reference.md b/OpenTelemetryPlan/05-configuration-reference.md index cf0f993dda..6170f932eb 100644 --- a/OpenTelemetryPlan/05-configuration-reference.md +++ b/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_`. 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_`. 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.). diff --git a/cfg/xrpld-example.cfg b/cfg/xrpld-example.cfg index 8464b68bcb..90f6c4f086 100644 --- a/cfg/xrpld-example.cfg +++ b/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 —