Merge branch 'pratik/otel-phase8-log-correlation' into pratik/otel-phase9-metric-gap-fill

OpenTelemetryPlan/02-design-decisions.md

@@ -635,6 +635,8 @@ span->SetAttribute("peer.id", peerId);
 
 ### 2.6.4 Coexistence Strategy
 
+> **Note**: Phase 7 replaces the StatsD bridge with native OTel Metrics SDK export. The diagram below shows the Phase 6 intermediate state. See [Phase7_taskList.md](./Phase7_taskList.md) for the migration design where Beast Insight emits via OTLP instead of StatsD.
+
 ```mermaid
 flowchart TB
     subgraph xrpld["xrpld Process"]
@@ -663,6 +665,8 @@ flowchart TB
 - **OpenTelemetry to OTLP Collector**: OTel exports spans over OTLP/gRPC to a Collector, which then forwards to a trace backend (Tempo).
 - **Grafana (red, unified UI)**: All three data streams converge in Grafana, enabling operators to correlate logs, metrics, and traces in a single dashboard.
 
+**Phase 7 target state**: Beast Insight routes to `OTelCollector` (new `Collector` implementation) which exports via OTLP/HTTP to the same collector endpoint as traces. StatsD UDP path becomes a deprecated fallback (`[insight] server=statsd`). See [06-implementation-phases.md §6.8](./06-implementation-phases.md) and [Phase7_taskList.md](./Phase7_taskList.md) for details.
+
 ### 2.6.5 Correlation with PerfLog
 
 Trace IDs can be correlated with existing PerfLog entries for comprehensive debugging:

OpenTelemetryPlan/05-configuration-reference.md

@@ -923,18 +923,22 @@ jsonData:
     filterBySpanID: false
 ```
 
-### 5.8.7 Correlation with Insight/StatsD Metrics
+### 5.8.7 Correlation with Insight/OTel System Metrics
 
-To correlate traces with existing Beast Insight metrics:
+To correlate traces with Beast Insight system metrics:
 
 **Step 1: Export Insight metrics to Prometheus**
 
-```yaml
-# prometheus.yaml
-scrape_configs:
-  - job_name: "xrpld-statsd"
-    static_configs:
-      - targets: ["statsd-exporter:9102"]
+Beast Insight metrics are exported natively via OTLP to the OTel Collector,
+which exposes them on the Prometheus endpoint alongside spanmetrics. No
+separate StatsD exporter is needed when using `server=otel`.
+
+```ini
+# xrpld.cfg — native OTel metrics (recommended)
+[insight]
+server=otel
+endpoint=http://localhost:4318/v1/metrics
+prefix=xrpld
 ```
 
 **Step 2: Add exemplars to metrics**