feat: add instrumentation feature

kaimast · kaimast · commit 0d0b94b5db04 · 2025-09-24T14:05:40.000-07:00
This feature adds `tracing::instrument` to various functions in snarkVM.
diff --git a/Cargo.lock b/Cargo.lock
diff --git a/Cargo.toml b/Cargo.toml
@@ -143,6 +143,7 @@ locktick = [
   "snarkvm-parameters?/locktick",
   "snarkvm-synthesizer?/locktick"
 ]
+instrumentation = [ "snarkvm-ledger/instrumentation" ]
 noconfig = [ ]
 rocks = [ "snarkvm-ledger/rocks", "snarkvm-synthesizer/rocks" ]
 test = [ "snarkvm-ledger/test" ]
diff --git a/README.md b/README.md
@@ -13,9 +13,10 @@
 ## Table of Contents
 
 * [1. Overview](#1-overview)
-* [2. Build Guide](#2-build-guide)
-* [3. Contributors](#3-contributors)
-* [4. License](#4-license)
+* [2. Usage Guide](#2-usage-guide)
+* [3. Build Guide](#3-build-guide)
+* [4. Contributors](#4-contributors)
+* [5. License](#5-license)
 
 ## 1. Overview
 
@@ -35,9 +36,51 @@
   
 For more information, visit [Welcome to Aleo](https://github.com/AleoNet/welcome) to get started.
 
-## 2. Build Guide
+## 2. Usage Guide
 
-### 2.1 Install Rust
+snarkVM is primarily designed to be used as a library in Rust projects. Add it to your `Cargo.toml` with your favourite published version:
+
+```toml
+[dependencies]
+snarkvm = "<major>.<minor>.<patch>"
+```
+
+### 2.1 Feature Flags
+
+The following is an (incomplete) list of features flags in the snarkVM crate.
+
+* **cuda** -
+  Allows some operations to run on the (NVidia) GPU, instead of on the CPU.
+* **cli** -
+  Enables the command-line interface. Needed when installing the `snarkvm` binary.
+* **locktick** -
+  This feature turns on code for detecting deadlocks.
+* **test_targets** -
+  This feature allows the lowering of coinbase and proof targets for testing.
+* **instrumentation** -
+  Adds `tracing::instrument` statements to (some) functions. This is useful for profiling, but should not be used in production.
+* **serial** -
+  *Disables* paralle processing using `rayon`.
+* **algorithms** -
+  Adds the `algorithms` crate to `snarkvm` (as `snarkvm::algorithms`)
+* **circuit** -
+  Adds the `circuit` crate to `snarkvm` (as `snarkvm::circuit`)
+* **fields** -
+  Adds the `fields` crate to `snarkvm` (as `snarkvm::fields`)
+* **ledger** -
+  Adds the `ledger` crate to `snarkvm` (as `snarkvm::ledger`)
+* **synthesizer** -
+  Adds the `synthesizer` crate to `snarkvm` (as `snarkvm::synthesizer`)
+* **parameters** -
+  Adds the `parameters` crate to `snarkvm` (as `snarkvm::parameters`)
+* **wasm** -
+  Enables behavior specific for WebAssembly. This feature should only be enabled when compiling to the `wasm32` architecture.
+
+### 3. Building Guide
+
+You can also build snarkVM from source. Because snarkVM is a library, this follwing guide is only useful if you plan to make modifications to its source code.
+
+### 3.1 Install Rust
 
 We recommend installing Rust using [rustup](https://www.rustup.rs/). You can install `rustup` as follows:
 
@@ -49,30 +92,34 @@ We recommend installing Rust using [rustup](https://www.rustup.rs/). You can ins
 - Windows (64-bit):
 
   Download the [Windows 64-bit executable](https://win.rustup.rs/x86_64) or
-  [Windows 32-bit executable](https://win.rustup.rs/i686) and follow the on-screen instructions.
+  [Windows 32-bit executable](https://win.rustup.rs/i686) and follow the on-screen instructions.i
 
-### 2.2 Using snarkVM as a Library
+### 3.2 Additional Dependencies
 
-snarkVM is primarily designed to be used as a library in Rust projects. Add it to your `Cargo.toml` with your favourite published version:
+On Linux, you also need the `lld` linker. For example, on a Debian system you would run the following to install it.
 
-```toml
-[dependencies]
-snarkvm = "<major>.<minor>.<patch>"
+```
+sudo apt install lld
 ```
 
-### 2.3 Build from Source Code
+### 3.3 Fetch Source Code
 
-You can also build snarkVM from source:
+The following snippet clones the `staging` branch of snarkVM. 
 
 ```bash
-# Fetch the repository's development (staging) branch
 git clone --branch staging --single-branch https://github.com/ProvableHQ/snarkVM.git 
 cd snarkVM
-# Build the library
+```
+
+### 3.4 Compiling snarkVM
+
+The following compiles the snarkVM crate.
+
+```
 cargo build --release
 ```
 
-## 3. Contributors
+## 4. Contributors
 
 Thank you for helping make snarkVM better!  
 [🧐 What do the emojis mean?](https://allcontributors.org/docs/en/emoji-key)
@@ -154,6 +201,6 @@ Thank you for helping make snarkVM better!
 
 This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!
 
-## 4. License
+## 5. License
 
 [![License: GPL v3](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](./LICENSE.md)
diff --git a/ledger/Cargo.toml b/ledger/Cargo.toml
@@ -57,6 +57,11 @@ serial = [
   "snarkvm-ledger-store/serial",
   "snarkvm-synthesizer/serial"
 ]
+instrumentation = [
+  "snarkvm-synthesizer/instrumentation",
+  "snarkvm-ledger-block/instrumentation",
+  "snarkvm-ledger-store/instrumentation"
+]
 test = [
   "snarkvm-console/test",
   "snarkvm-ledger-block/test",
diff --git a/ledger/block/Cargo.toml b/ledger/block/Cargo.toml
@@ -34,6 +34,7 @@ wasm = [
   "snarkvm-synthesizer-program/wasm",
   "snarkvm-synthesizer-snark/wasm"
 ]
+instrumentation = [ "dep:tracing" ]
 test = [ "snarkvm-synthesizer-process/test" ]
 
 [dependencies.snarkvm-console]
@@ -76,6 +77,10 @@ version = "1"
 workspace = true
 features = [ "serde" ]
 
+[dependencies.tracing]
+workspace = true
+optional = true
+
 [dependencies.rayon]
 workspace = true
 
diff --git a/ledger/block/src/verify.rs b/ledger/block/src/verify.rs
@@ -27,6 +27,7 @@ use rayon::prelude::*;
 
 impl<N: Network> Block<N> {
     /// Ensures the block is correct.
+    #[cfg_attr(feature = "instrumentation", tracing::instrument(skip_all))]
     pub fn verify(
         &self,
         previous_block: &Block<N>,
diff --git a/ledger/src/advance.rs b/ledger/src/advance.rs
@@ -92,6 +92,7 @@ impl<N: Network, C: ConsensusStorage<N>> Ledger<N, C> {
     }
 
     /// Adds the given block as the next block in the ledger.
+    #[cfg_attr(feature = "instrumentation", tracing::instrument(skip_all))]
     pub fn advance_to_next_block(&self, block: &Block<N>) -> Result<()> {
         // Acquire the write lock on the current block.
         let mut current_block = self.current_block.write();
diff --git a/ledger/src/check_next_block.rs b/ledger/src/check_next_block.rs
@@ -19,6 +19,7 @@ use crate::narwhal::BatchHeader;
 
 impl<N: Network, C: ConsensusStorage<N>> Ledger<N, C> {
     /// Checks the given block is valid next block.
+    #[cfg_attr(feature = "instrumentation", tracing::instrument(skip(self, block, pending_blocks)))]
     pub fn check_next_block<R: CryptoRng + Rng>(&self, block: &Block<N>, rng: &mut R) -> Result<()> {
         let height = block.height();
         let latest_block = self.latest_block();
@@ -154,6 +155,7 @@ impl<N: Network, C: ConsensusStorage<N>> Ledger<N, C> {
     ///
     /// This does not verify that the batches are signed correctly or that the edges are valid
     /// (only point to the previous round), as those checks already happened when the node received the batch.
+    #[cfg_attr(feature = "instrumentation", tracing::instrument(skip(self, block, previous_blocks)))]
     fn check_block_subdag_leaves(&self, block: &Block<N>) -> Result<()> {
         // Check if the block has a subdag.
         let Authority::Quorum(subdag) = block.authority() else {
@@ -193,6 +195,9 @@ impl<N: Network, C: ConsensusStorage<N>> Ledger<N, C> {
     }
 
     /// Check that the certificates in the block subdag have met quorum requirements.
+    ///
+    /// Called by [`Self::check_block_subdag`]
+    #[cfg_attr(feature = "instrumentation", tracing::instrument(skip(self, block)))]
     fn check_block_subdag_quorum(&self, block: &Block<N>) -> Result<()> {
         // Check if the block has a subdag.
         let subdag = match block.authority() {
diff --git a/ledger/src/get.rs b/ledger/src/get.rs
@@ -50,6 +50,7 @@ impl<N: Network, C: ConsensusStorage<N>> Ledger<N, C> {
     }
 
     /// Returns the committee lookback for the given round.
+    #[cfg_attr(feature = "instrumentation", tracing::instrument(skip(self)))]
     pub fn get_committee_lookback_for_round(&self, round: u64) -> Result<Option<Committee<N>>> {
         // Get the round number for the previous committee. Note, we subtract 2 from odd rounds,
         // because committees are updated in even rounds.
diff --git a/ledger/store/Cargo.toml b/ledger/store/Cargo.toml
@@ -19,7 +19,7 @@ edition = "2024"
 [features]
 default = [ "indexmap/rayon" ]
 locktick = [ "dep:locktick", "snarkvm-ledger-puzzle/locktick" ]
-rocks = [ "rocksdb", "smallvec", "tracing" ]
+rocks = [ "dep:rocksdb", "dep:smallvec", "dep:tracing" ]
 serial = [
   "snarkvm-console/serial",
   "snarkvm-ledger-block/serial",
@@ -39,6 +39,7 @@ wasm = [
   "snarkvm-synthesizer-snark/wasm"
 ]
 test = [ ]
+instrumentation = [ "dep:tracing" ]
 
 [dependencies.snarkvm-console]
 workspace = true
diff --git a/ledger/store/src/block/mod.rs b/ledger/store/src/block/mod.rs
@@ -722,6 +722,7 @@ pub trait BlockStorage<N: Network>: 'static + Clone + Send + Sync {
     }
 
     /// Returns the previous block hash of the given `block height`.
+    #[cfg_attr(feature = "instrumentation", tracing::instrument(skip(self)))]
     fn get_previous_block_hash(&self, height: u32) -> Result<Option<N::BlockHash>> {
         if height.is_zero() {
             Ok(Some(N::BlockHash::default()))
@@ -731,11 +732,13 @@ pub trait BlockStorage<N: Network>: 'static + Clone + Send + Sync {
     }
 
     /// Returns the block hash for the given `block height`.
+    #[cfg_attr(feature = "instrumentation", tracing::instrument(skip(self)))]
     fn get_block_hash(&self, height: u32) -> Result<Option<N::BlockHash>> {
         Ok(self.id_map().get_confirmed(&height)?.map(|x| *x))
     }
 
     /// Returns the block height for the given `block hash`.
+    #[cfg_attr(feature = "instrumentation", tracing::instrument(skip(self)))]
     fn get_block_height(&self, block_hash: &N::BlockHash) -> Result<Option<u32>> {
         Ok(self.reverse_id_map().get_confirmed(block_hash)?.map(|x| *x))
     }
@@ -756,6 +759,8 @@ pub trait BlockStorage<N: Network>: 'static + Clone + Send + Sync {
     }
 
     /// Returns the batch certificate for the given `certificate ID`.
+    ///
+    #[cfg_attr(feature = "instrumentation", tracing::instrument(skip(self)))]
     fn get_batch_certificate(&self, certificate_id: &Field<N>) -> Result<Option<BatchCertificate<N>>> {
         // Retrieve the height and round for the given certificate ID.
         let Some((block_height, round)) = self.certificate_map().get_confirmed(certificate_id)?.map(|x| *x) else {
@@ -849,6 +854,7 @@ pub trait BlockStorage<N: Network>: 'static + Clone + Send + Sync {
     }
 
     /// Returns the transaction for the given `TransactionID`.
+    #[cfg_attr(feature = "instrumentation", tracing::instrument(skip(self)))]
     fn get_transaction(&self, transaction_id: &N::TransactionID) -> Result<Option<Transaction<N>>> {
         // Check if the transaction was rejected or aborted.
         // Note: We can only retrieve accepted or rejected transactions. We cannot retrieve aborted transactions.
@@ -928,7 +934,8 @@ pub trait BlockStorage<N: Network>: 'static + Clone + Send + Sync {
         }
     }
 
-    /// Returns the block for the given `block hash`.
+    /// Returns the block for the given `block_hash`.
+    #[cfg_attr(feature = "instrumentation", tracing::instrument(skip(self)))]
     fn get_block(&self, block_hash: &N::BlockHash) -> Result<Option<Block<N>>> {
         // Retrieve the block height.
         let Some(height) = self.get_block_height(block_hash)? else { return Ok(None) };
diff --git a/synthesizer/Cargo.toml b/synthesizer/Cargo.toml
@@ -46,6 +46,7 @@ serial = [
   "snarkvm-synthesizer-snark/serial"
 ]
 setup = [ ]
+instrumentation = [ "snarkvm-synthesizer-program/instrumentation" ]
 test = [ "snarkvm-console/test", "snarkvm-synthesizer-process/test" ]
 timer = [ "aleo-std/timer" ]
 wasm = [
diff --git a/synthesizer/program/Cargo.toml b/synthesizer/program/Cargo.toml
@@ -25,6 +25,7 @@ edition = "2024"
 
 [features]
 default = [ ]
+instrumentation = [ "dep:tracing" ]
 serial = [ "snarkvm-console/serial" ]
 wasm = [ "snarkvm-console/wasm" ]
 
@@ -56,6 +57,10 @@ workspace = true
 [dependencies.rayon]
 version = "1"
 
+[dependencies.tracing]
+workspace = true
+optional = true
+
 [dependencies.serde_json]
 workspace = true
 features = [ "preserve_order" ]
diff --git a/synthesizer/program/src/logic/finalize_global_state/mod.rs b/synthesizer/program/src/logic/finalize_global_state/mod.rs
@@ -47,6 +47,7 @@ impl FinalizeGlobalState {
 
     /// Initializes a new global state from the given inputs.
     #[inline]
+    #[cfg_attr(feature = "instrumentation", tracing::instrument(skip_all))]
     pub fn new<N: Network>(
         block_round: u64,
         block_height: u32,

Original file line number	Diff line number	Diff line change
`@@ -143,6 +143,7 @@ locktick = [`
`143`	`143`	`"snarkvm-parameters?/locktick",`
`144`	`144`	`"snarkvm-synthesizer?/locktick"`
`145`	`145`	`]`
	`146`	`+instrumentation = [ "snarkvm-ledger/instrumentation" ]`
`146`	`147`	`noconfig = [ ]`
`147`	`148`	`rocks = [ "snarkvm-ledger/rocks", "snarkvm-synthesizer/rocks" ]`
`148`	`149`	`test = [ "snarkvm-ledger/test" ]`
Original file line number	Diff line number	Diff line change
`@@ -92,6 +92,7 @@ impl<N: Network, C: ConsensusStorage<N>> Ledger<N, C> {`
`92`	`92`	`}`
`93`	`93`
`94`	`94`	`/// Adds the given block as the next block in the ledger.`
	`95`	`+ #[cfg_attr(feature = "instrumentation", tracing::instrument(skip_all))]`
`95`	`96`	`pub fn advance_to_next_block(&self, block: &Block<N>) -> Result<()> {`
`96`	`97`	`// Acquire the write lock on the current block.`
`97`	`98`	`let mut current_block = self.current_block.write();`
Original file line number	Diff line number	Diff line change
`@@ -50,6 +50,7 @@ impl<N: Network, C: ConsensusStorage<N>> Ledger<N, C> {`
`50`	`50`	`}`
`51`	`51`
`52`	`52`	`/// Returns the committee lookback for the given round.`
	`53`	`+ #[cfg_attr(feature = "instrumentation", tracing::instrument(skip(self)))]`
`53`	`54`	`pub fn get_committee_lookback_for_round(&self, round: u64) -> Result<Option<Committee<N>>> {`
`54`	`55`	`// Get the round number for the previous committee. Note, we subtract 2 from odd rounds,`
`55`	`56`	`// because committees are updated in even rounds.`