From f4cde7a51c43952c7aa445a303383ae13d04e364 Mon Sep 17 00:00:00 2001
From: Illia Bobyr <illia.bobyr@solana.com>
Date: Mon, 20 Mar 2023 13:50:58 -0700
Subject: [PATCH] doc: ledger: Document `ConfirmationTiming` (#30784)

There is some logic related to how timing values are collected that is not immediately obvious. It is better to document it, rather than requiring everyone interested to reverse engineer it from the code.
---
 ledger/src/blockstore_processor.rs | 27 +++++++++++++++++++++++++++
 1 file changed, 27 insertions(+)

diff --git a/ledger/src/blockstore_processor.rs b/ledger/src/blockstore_processor.rs
index fb8df9cf71..552d88ae08 100644
--- a/ledger/src/blockstore_processor.rs
+++ b/ledger/src/blockstore_processor.rs
@@ -909,16 +909,43 @@ fn confirm_full_slot(
     }
 }
 
+/// Measures different parts of the slot confirmation processing pipeline.
 #[derive(Debug)]
 pub struct ConfirmationTiming {
+    /// Moment when the `ConfirmationTiming` instance was created.  Used to track the total wall
+    /// clock time from the moment the first shard for the slot is received and to the moment the
+    /// slot is complete.
     pub started: Instant,
+
+    /// Wall clock time used by the entry replay code.  Does not include the PoH or the transaction
+    /// signature/precompiles verification, but can overlap with the PoH and signature verification.
+    /// In microseconds.
     pub replay_elapsed: u64,
+
+    /// Wall clock time used by the transaction execution part of pipeline.  `replay_elapsed`
+    /// includes this time.  In microseconds.
     pub execute_batches_us: u64,
+
+    /// Wall clock times, used for the PoH verification of entries.  In microseconds.
     pub poh_verify_elapsed: u64,
+
+    /// Wall clock time, used for the signature verification as well as precompiles verification.
+    /// In microseconds.
     pub transaction_verify_elapsed: u64,
+
+    /// Wall clock time spent loading data sets (and entries) from the blockstore.  This does not
+    /// include the case when the blockstore load failed.  In microseconds.
     pub fetch_elapsed: u64,
+
+    /// Same as `fetch_elapsed` above, but for the case when the blockstore load fails.  In
+    /// microseconds.
     pub fetch_fail_elapsed: u64,
+
+    /// Time used in transaction execution.  Across multiple threads, running `execute_batch()`.
     pub execute_timings: ExecuteTimings,
+
+    /// Time used to execute transactions, via `execute_batch()`, in the thread that consumed the
+    /// most time.
     pub end_to_end_execute_timings: ThreadExecuteTimings,
 }