DOC-15352: Replace use of metrics-list.csv with metrics.yaml in metrics generated pages

src/current/_data/v25.4/metrics/metrics-cloud.yml

@@ -91,6 +91,7 @@
   metric_type: "Request Units"
   metric_ui_tab: [ Overview, "Request Units"]
   metric_ui_graph: "Request Units"
+  how_to_use: 'The CPU and I/O resources being used by queries in the cluster. Simple queries consume few RUs, while complicated queries with many reads and writes consume more RUs. To learn more about how RUs are calculated, refer to Resource Usage.'
 
 - metric_id: livebytes
   deploy_selfhosted: true
@@ -103,6 +104,7 @@
   metric_type: Storage
   metric_ui_tab: [ Overview ]
   metric_ui_graph: Storage
+  how_to_use: 'The amount of data being stored in the cluster. In the Storage Used graph, this is the logical number of live bytes and does not account for compression or replication.'
 
 - metric_id: tenant.consumption.sql_pods_cpu_seconds
   deploy_selfhosted: false
@@ -115,6 +117,12 @@
   metric_type: "Request Units"
   metric_ui_tab: [ "Request Units" ]
   metric_ui_graph: "CPU"
+  how_to_use: |
+    The number of RUs consumed by CPU usage of SQL processes (not storage processes). The CPU seconds is converted to Request Units using this equivalency:
+
+    1 RU = 3 milliseconds SQL CPU.
+
+    Correlate this metric with Request Units (RUs) and determine if your workload is CPU-intensive. To learn more about how RUs are calculated, refer to Resource Usage.'
 
 - metric_id: tenant.consumption.pgwire_egress_bytes
   deploy_selfhosted: false
@@ -127,6 +135,12 @@
   metric_type: "Request Units"
   metric_ui_tab: [ "Request Units" ]
   metric_ui_graph: "Egress"
+  how_to_use: |
+    The number of RUs consumed by byte traffic to the client. Egress bytes are converted to Request Units using this equivalency:
+
+    1 RU = 1 KiB Network egress.
+
+    Correlate this metric with Request Units (RUs). To learn more about how RUs are calculated, refer to Resource Usage.'
 
 - metric_id: tenant.consumption.external_io_egress_bytes
   deploy_selfhosted: false
@@ -139,6 +153,12 @@
   metric_type: "Request Units"
   metric_ui_tab: [ "Request Units" ]
   metric_ui_graph: "Egress"
+  how_to_use: |
+    The number of RUs consumed by byte traffic for cluster bulk I/O operations (e.g., CDC). Egress bytes are converted to Request Units using this equivalency:
+
+    1 RU = 1 KiB Network egress.
+
+    Correlate this metric with Request Units (RUs). To learn more about how RUs are calculated, refer to Resource Usage.
 
 - metric_id: tenant.consumption.read_requests
   deploy_selfhosted: false
@@ -151,7 +171,13 @@
   metric_type: "Request Units"
   metric_ui_tab: [ "Request Units" ]
   metric_ui_graph: "Reads"
-
+  how_to_use: |
+    The number of RUs consumed by KV storage layer reads, broken down by requests. SQL statements are translated into lower-level KV read requests that are sent in batches. Batches may contain any number of requests. Requests can have a payload containing any number of bytes. Storage layer I/O is converted to Request Units using this equivalency:
+
+    1 RU = 8 storage read requests
+
+    Correlate this metric with Request Units (RUs). To learn more about how RUs are calculated, refer to Resource Usage.
+
 - metric_id: tenant.consumption.read_batches
   deploy_selfhosted: false
   deploy_dedicated: false
@@ -163,6 +189,12 @@
   metric_type: "Request Units"
   metric_ui_tab: [ "Request Units" ]
   metric_ui_graph: "Reads"
+  how_to_use: |
+    The number of RUs consumed by KV storage layer reads, broken down by batches. SQL statements are translated into lower-level KV read requests that are sent in batches. Batches may contain any number of requests. Requests can have a payload containing any number of bytes. Storage layer I/O is converted to Request Units using this equivalency:
+
+    1 RU = 2 storage read batches
+
+    Correlate this metric with Request Units (RUs). To learn more about how RUs are calculated, refer to Resource Usage.
 
 - metric_id: tenant.consumption.read_bytes
   deploy_selfhosted: false
@@ -175,6 +207,12 @@
   metric_type: "Request Units"
   metric_ui_tab: [ "Request Units" ]
   metric_ui_graph: "Reads"
+  how_to_use: |
+    The number of RUs consumed by KV storage layer reads, broken down by bytes. SQL statements are translated into lower-level KV read requests that are sent in batches. Batches may contain any number of requests. Requests can have a payload containing any number of bytes. Storage layer I/O is converted to Request Units using this equivalency:
+
+    1 RU = 64 KiB read request payload (prorated)
+
+    Correlate this metric with Request Units (RUs). To learn more about how RUs are calculated, refer to Resource Usage.
 
 - metric_id: tenant.consumption.write_requests
   deploy_selfhosted: false
@@ -187,6 +225,12 @@
   metric_type: "Request Units"
   metric_ui_tab: [ "Request Units" ]
   metric_ui_graph: "Writes"
+  how_to_use: |
+    The number of RUs consumed by KV writes, broken down by requests. SQL statements are translated into lower-level KV write requests that are sent in batches. Batches may contain any number of requests. Requests can have a payload containing any number of bytes. Write operations are replicated to multiple storage processes (3 by default), with each replica counted as a separate write operation. Storage layer I/O is converted to Request Units using this equivalency:
+
+    1 RU = 1 storage write request
+
+    Correlate this metric with Request Units (RUs). To learn more about how RUs are calculated, refer to Resource Usage.
 
 - metric_id: tenant.consumption.write_batches
   deploy_selfhosted: false
@@ -199,6 +243,12 @@
   metric_type: "Request Units"
   metric_ui_tab: [ "Request Units" ]
   metric_ui_graph: "Writes"
+  how_to_use: |
+    The number of RUs consumed by KV writes, broken down by batches. SQL statements are translated into lower-level KV write requests that are sent in batches. Batches may contain any number of requests. Requests can have a payload containing any number of bytes. Write operations are replicated to multiple storage processes (3 by default), with each replica counted as a separate write operation. Storage layer I/O is converted to Request Units using this equivalency:
+
+    1 RU = 1 storage write batch
+
+    Correlate this metric with Request Units (RUs). To learn more about how RUs are calculated, refer to Resource Usage.
 
 - metric_id: tenant.consumption.write_bytes
   deploy_selfhosted: false
@@ -211,6 +261,12 @@
   metric_type: "Request Units"
   metric_ui_tab: [ "Request Units" ]
   metric_ui_graph: "Writes"
+  how_to_use: |
+    The number of RUs consumed by KV writes, broken down by bytes. SQL statements are translated into lower-level KV write requests that are sent in batches. Batches may contain any number of requests. Requests can have a payload containing any number of bytes. Write operations are replicated to multiple storage processes (3 by default), with each replica counted as a separate write operation. Storage layer I/O is converted to Request Units using this equivalency:
+
+    1 RU = 1 KiB write request payload (prorated)
+
+    Correlate this metric with Request Units (RUs). To learn more about how RUs are calculated, refer to Resource Usage.
 
 - metric_id: tenant.consumption.cross_region_network_ru
   deploy_selfhosted: false
@@ -223,6 +279,7 @@
   metric_type: "Request Units"
   metric_ui_tab: [ "Request Units" ]
   metric_ui_graph: "Cross-region Networking"
+  how_to_use: 'The number of RUs consumed by cross-region networking. Correlate these metrics with Request Units (RUs). For more information about multi-region clusters and networking, refer to Multi-region clusters.'
 
 - metric_id: sql.conn.latency
   deploy_selfhosted: true
@@ -331,6 +388,7 @@
   metric_type: SQL
   metric_ui_tab: [ SQL ]
   metric_ui_graph: "Transaction Restarts"
+  how_to_use: 'This metric is one measure of the impact of contention conflicts on workload performance. For guidance on contention conflicts, review transaction contention best practices and performance tuning recipes. Tens of restarts per minute may be a high value, a signal of an elevated degree of contention in the workload, which should be investigated. For the specific error, refer to the transaction retry error reference for more details.'
 
 - metric_id: txn.restarts.serializable
   deploy_selfhosted: true
@@ -355,6 +413,7 @@
   metric_type: SQL
   metric_ui_tab: [ SQL ]
   metric_ui_graph: "Transaction Restarts"
+  how_to_use: 'This metric is one measure of the impact of contention conflicts on workload performance. For guidance on contention conflicts, review transaction contention best practices and performance tuning recipes. Tens of restarts per minute may be a high value, a signal of an elevated degree of contention in the workload, which should be investigated. For the specific error, refer to the transaction retry error reference for more details.'
 
 - metric_id: txn.restarts.readwithinuncertainty
   deploy_selfhosted: false
@@ -367,6 +426,7 @@
   metric_type: SQL
   metric_ui_tab: [ SQL ]
   metric_ui_graph: "Transaction Restarts"
+  how_to_use: 'This metric is one measure of the impact of contention conflicts on workload performance. For guidance on contention conflicts, review transaction contention best practices and performance tuning recipes. Tens of restarts per minute may be a high value, a signal of an elevated degree of contention in the workload, which should be investigated. For the specific error, refer to the transaction retry error reference for more details.'
 
 - metric_id: txn.restarts.txnaborted
   deploy_selfhosted: true