From 42615355bea0daf63f1c5c1ba2759a23003d0346 Mon Sep 17 00:00:00 2001
From: Pratik Mankawde <3397372+pratikmankawde@users.noreply.github.com>
Date: Tue, 21 Jul 2026 20:33:56 +0100
Subject: [PATCH] docs(telemetry): add rpc_in_flight_requests to metric-surface
 reference (09-doc)

---
 .../09-data-collection-reference.md            | 18 ++++++++++++------
 1 file changed, 12 insertions(+), 6 deletions(-)

diff --git a/OpenTelemetryPlan/09-data-collection-reference.md b/OpenTelemetryPlan/09-data-collection-reference.md
index b2724b79bd..fad3e59b45 100644
--- a/OpenTelemetryPlan/09-data-collection-reference.md
+++ b/OpenTelemetryPlan/09-data-collection-reference.md
@@ -1035,12 +1035,18 @@ via OTLP/HTTP to the OTel Collector and scraped by Prometheus.
 
 #### Per-RPC Method Metrics (Synchronous Counters/Histogram)
 
-| Prometheus Metric           | Type      | Labels            | Description                      |
-| --------------------------- | --------- | ----------------- | -------------------------------- |
-| `rpc_method_started_total`  | Counter   | `method="<name>"` | RPC calls started                |
-| `rpc_method_finished_total` | Counter   | `method="<name>"` | RPC calls completed successfully |
-| `rpc_method_errored_total`  | Counter   | `method="<name>"` | RPC calls that errored           |
-| `rpc_method_us`             | Histogram | `method="<name>"` | Execution time distribution (us) |
+| Prometheus Metric           | Type          | Labels            | Description                                            |
+| --------------------------- | ------------- | ----------------- | ------------------------------------------------------ |
+| `rpc_method_started_total`  | Counter       | `method="<name>"` | RPC calls started                                      |
+| `rpc_method_finished_total` | Counter       | `method="<name>"` | RPC calls completed successfully                       |
+| `rpc_method_errored_total`  | Counter       | `method="<name>"` | RPC calls that errored                                 |
+| `rpc_method_us`             | Histogram     | `method="<name>"` | Execution time distribution (us)                       |
+| `rpc_in_flight_requests`    | UpDownCounter | (none)            | RPC calls currently executing (+1 rpcStart, -1 rpcEnd) |
+
+`rpc_in_flight_requests` is emitted at its call site via the `XRPL_METRIC_UPDOWN_ADD`
+macro (see `src/xrpld/telemetry/MetricMacros.h` and `PerfLogImp.cpp`), not through a
+`MetricsRegistry` member. As an UpDownCounter it carries no `_total` suffix (that is
+reserved for monotonic counters).
 
 #### Per-Job-Type Metrics (Synchronous Counters/Histogram)