[Feature] Add tracing::instrument to allow generating flame graphs

Cargo.toml

@@ -134,6 +134,7 @@ locktick = [
   "snarkvm-parameters?/locktick",
   "snarkvm-synthesizer?/locktick"
 ]
+instrumentation = [ "snarkvm-ledger/instrumentation" ]
 noconfig = [ ]
 rocks = [ "snarkvm-ledger/rocks", "snarkvm-synthesizer/rocks" ]
 test = [ "snarkvm-ledger/test" ]

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* parallel processing using `rayon`. This is useful for specialized profiling, but should not be used in production.
+* **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 following 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:
 
@@ -57,28 +100,32 @@ We recommend installing Rust using [rustup](https://www.rustup.rs/). You can ins
   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.
 
-### 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)
@@ -160,6 +207,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)

ledger/Cargo.toml

@@ -81,6 +81,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",

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" ]
 test-helpers = [ ]
 
@@ -77,6 +78,10 @@ version = "1"
 workspace = true
 features = [ "serde" ]
 
+[dependencies.tracing]
+workspace = true
+optional = true
+
 [dependencies.rayon]
 workspace = true
 

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, fields(height=self.height())))]
     pub fn verify(
         &self,
         previous_block: &Block<N>,

ledger/src/advance.rs

@@ -101,6 +101,7 @@ impl<N: Network, C: ConsensusStorage<N>> Ledger<N, C> {
     ///
     /// # Panics
     /// This function panics if called from an async context.
+    #[cfg_attr(feature = "instrumentation", tracing::instrument(skip_all, fields(height=block.height())))]
     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();

ledger/src/check_next_block.rs

@@ -24,6 +24,7 @@ impl<N: Network, C: ConsensusStorage<N>> Ledger<N, C> {
     ///
     /// # Panics
     /// This function panics if called from an async context.
+    #[cfg_attr(feature = "instrumentation", tracing::instrument(skip_all, fields(height=block.height())))]
     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();
@@ -145,6 +146,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_all, fields(height=block.height())))]
     fn check_block_subdag_leaves(&self, block: &Block<N>) -> Result<()> {
         // Check if the block has a subdag.
         let Authority::Quorum(subdag) = block.authority() else {
@@ -184,6 +186,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_all, fields(height=block.height())))]
     fn check_block_subdag_quorum(&self, block: &Block<N>) -> Result<()> {
         // Check if the block has a subdag.
         let subdag = match block.authority() {

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.

ledger/store/Cargo.toml

@@ -19,7 +19,7 @@ edition = "2024"
 [features]
 default = [ "indexmap/rayon" ]
 locktick = [ "dep:locktick", "snarkvm-ledger-puzzle/locktick" ]
-rocks = [ "rocksdb", "smallvec" ]
+rocks = [ "dep:rocksdb", "dep:smallvec" ]
 serial = [
   "snarkvm-console/serial",
   "snarkvm-ledger-block/serial",
@@ -39,6 +39,7 @@ wasm = [
   "snarkvm-synthesizer-snark/wasm"
 ]
 test = [ ]
+instrumentation = [ ]
 
 [dependencies.snarkvm-console]
 workspace = true

ledger/store/src/block/mod.rs

@@ -726,6 +726,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()))
@@ -735,11 +736,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))
     }
@@ -760,6 +763,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 {
@@ -853,6 +858,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.
@@ -932,7 +938,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) };

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 = [

synthesizer/program/Cargo.toml

@@ -25,6 +25,7 @@ edition = "2024"
 
 [features]
 default = [ ]
+instrumentation = [ "dep:tracing" ]
 serial = [ "snarkvm-console/serial" ]
 wasm = [ "snarkvm-console/wasm" ]
 
@@ -59,6 +60,10 @@ workspace = true
 [dependencies.rayon]
 version = "1"
 
+[dependencies.tracing]
+workspace = true
+optional = true
+
 [dependencies.serde_json]
 workspace = true
 features = [ "preserve_order" ]

synthesizer/program/src/logic/finalize_global_state/mod.rs

@@ -50,6 +50,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,