feat: provide basic tracing spans for common operations.

This is just the beginning and more crates will integrate with it over time.

Author: Byron

.cargo/config.toml

@@ -2,7 +2,7 @@
 rustflags = [
     # Rustc lints
     # "-W", "warning_name"
-    # "-A", "warning_name"
+    "-A", "clippy::let_unit_value", # in 'small' builds this triggers as the `span!` macro yields `let x = ()`. No way to prevent it in macro apparently.
 
     # Clippy lints
     "-W", "clippy::cloned_instead_of_copied",

Cargo.lock

@@ -65,6 +65,7 @@ impl State {
             expected_checksum,
         }: Options,
     ) -> Result<(Self, gix_hash::ObjectId), Error> {
+        let _span = gix_features::trace::detail!("gix_index::State::from_bytes()");
         let (version, num_entries, post_header_data) = header::decode(data, object_hash)?;
         let start_of_extensions = extension::end_of_index_entry::decode(data, object_hash);
 

gix-index/src/decode/mod.rs

@@ -46,6 +46,7 @@ impl File {
 
     /// Open an index file at `path` with `options`, assuming `object_hash` is used throughout the file.
     pub fn at(path: impl Into<PathBuf>, object_hash: gix_hash::Kind, options: decode::Options) -> Result<Self, Error> {
+        let _span = gix_features::trace::detail!("gix_index::File::at()");
         let path = path.into();
         let (data, mtime) = {
             // SAFETY: we have to take the risk of somebody changing the file underneath. Git never writes into the same file.

gix-index/src/file/init.rs

@@ -55,6 +55,7 @@ pub struct Options {
 impl State {
     /// Serialize this instance to `out` with [`options`][Options].
     pub fn write_to(&self, out: impl std::io::Write, Options { extensions }: Options) -> std::io::Result<Version> {
+        let _span = gix_features::trace::detail!("gix_index::State::write()");
         let version = self.detect_required_version();
 
         let mut write = CountBytes::new(out);

gix-index/src/write.rs

@@ -79,6 +79,7 @@ impl Store {
             current_dir,
         }: Options,
     ) -> std::io::Result<Self> {
+        let _span = gix_features::trace::detail!("gix_odb::Store::at()");
         let objects_dir = objects_dir.into();
         let current_dir = current_dir.map_or_else(std::env::current_dir, Ok)?;
         if !objects_dir.is_dir() {

gix-odb/src/store_impls/dynamic/init.rs

@@ -85,6 +85,7 @@ where
         match *count {
             Some(count) => Ok(count),
             None => {
+                let _span = gix_features::trace::detail!("gix_odb::Handle::packed_object_count()");
                 let mut snapshot = self.snapshot.borrow_mut();
                 *snapshot = self.store.load_all_indices()?;
                 let mut obj_count = 0;

gix-odb/src/store_impls/dynamic/prefix.rs

@@ -52,6 +52,7 @@ impl Store {
     /// implementation. The likelihood of actual changes is low though as these still depend on something
     /// changing on disk and somebody reading at the same time.
     pub fn structure(&self) -> Result<Vec<Record>, load_index::Error> {
+        let _span = gix_features::trace::detail!("gix_odb::Store::structure()");
         let index = self.index.load();
         if !index.is_initialized() {
             self.consolidate_with_disk_state(true, false /*load one new index*/)?;

gix-odb/src/store_impls/dynamic/structure.rs

@@ -70,6 +70,7 @@ impl crate::Bundle {
         thin_pack_base_object_lookup_fn: Option<ThinPackLookupFn>,
         options: Options,
     ) -> Result<Outcome, Error> {
+        let _span = gix_features::trace::coarse!("gix_pack::Bundle::write_to_directory()");
         let mut read_progress = progress.add_child_with_id("read pack", ProgressId::ReadPackBytes.into());
         read_progress.init(None, progress::bytes());
         let pack = progress::Read {
@@ -183,6 +184,7 @@ impl crate::Bundle {
         P: Progress,
         P::SubProgress: 'static,
     {
+        let _span = gix_features::trace::coarse!("gix_pack::Bundle::write_to_directory_eagerly()");
         let mut read_progress = progress.add_child_with_id("read pack", ProgressId::ReadPackBytes.into()); /* Bundle Write Read pack Bytes*/
         read_progress.init(pack_size.map(|s| s as usize), progress::bytes());
         let pack = progress::Read {

gix-pack/src/bundle/write/mod.rs

@@ -13,6 +13,7 @@ rust-version = "1.64"
 doctest = false
 
 [dependencies]
+gix-trace = { version = "0.1.0", path = "../gix-trace" }
 bstr = { version = "1.3.0", default-features = false, features = ["std"] }
 thiserror = "1.0.26"
 once_cell = "1.17.1"

gix-path/Cargo.toml

@@ -8,6 +8,7 @@ use bstr::{BStr, BString, ByteSlice};
 /// Returns the file that contains git configuration coming with the installation of the `git` file in the current `PATH`, or `None`
 /// if no `git` executable was found or there were other errors during execution.
 pub(crate) fn install_config_path() -> Option<&'static BStr> {
+    let _span = gix_trace::detail!("gix_path::git::install_config_path()");
     static PATH: once_cell::sync::Lazy<Option<BString>> = once_cell::sync::Lazy::new(|| {
         // Shortcut: in Msys shells this variable is set which allows to deduce the installation directory
         // so we can save the `git` invocation.

gix-path/src/env/git.rs

@@ -141,6 +141,7 @@ gix-transport = { version = "^0.32.0", path = "../gix-transport", optional = tru
 gix-diff = { version = "^0.30.1", path = "../gix-diff" }
 gix-mailmap = { version = "^0.13.0", path = "../gix-mailmap" }
 gix-features = { version = "^0.30.0", path = "../gix-features", features = ["progress", "once_cell"] }
+gix-trace = { version = "^0.1.0", path = "../gix-trace" }
 
 gix-attributes = { version = "^0.13.1", path = "../gix-attributes" }
 gix-ignore = { version = "^0.3.0", path = "../gix-ignore" }

gix/Cargo.toml

@@ -69,6 +69,7 @@ pub mod main_worktree {
             mut progress: impl crate::Progress,
             should_interrupt: &AtomicBool,
         ) -> Result<(Repository, gix_worktree::checkout::Outcome), Error> {
+            let _span = gix_trace::coarse!("gix::clone::PrepareCheckout::main_worktree()");
             let repo = self
                 .repo
                 .as_ref()

gix/src/clone/checkout.rs

@@ -36,6 +36,7 @@ impl ThreadSafeRepository {
         options: upwards::Options<'_>,
         trust_map: gix_sec::trust::Mapping<crate::open::Options>,
     ) -> Result<Self, Error> {
+        let _span = gix_trace::coarse!("ThreadSafeRepository::discover()");
         let (path, trust) = upwards_opts(directory, options)?;
         let (git_dir, worktree_dir) = path.into_repository_and_work_tree_directories();
         let mut options = trust_map.into_value_by_level(trust);

gix/src/discover.rs

@@ -93,6 +93,7 @@ pub use gix_ref as refs;
 pub use gix_refspec as refspec;
 pub use gix_sec as sec;
 pub use gix_tempfile as tempfile;
+pub use gix_trace as trace;
 pub use gix_traverse as traverse;
 pub use gix_url as url;
 #[doc(inline)]

gix/src/lib.rs

@@ -51,6 +51,7 @@ impl ThreadSafeRepository {
     ///
     /// Note that you should use [`crate::discover()`] if security should be adjusted by ownership.
     pub fn open_opts(path: impl Into<PathBuf>, mut options: Options) -> Result<Self, Error> {
+        let _span = gix_trace::coarse!("ThreadSafeRepository::open()");
         let (path, kind) = {
             let path = path.into();
             let looks_like_git_dir =
@@ -103,6 +104,7 @@ impl ThreadSafeRepository {
         fallback_directory: impl Into<PathBuf>,
         trust_map: gix_sec::trust::Mapping<Options>,
     ) -> Result<Self, Error> {
+        let _span = gix_trace::coarse!("ThreadSafeRepository::open_with_environment_overrides()");
         let overrides = EnvironmentOverrides::from_env()?;
         let (path, path_kind): (PathBuf, _) = match overrides.git_dir {
             Some(git_dir) => gix_discover::is_git(&git_dir)
@@ -139,6 +141,7 @@ impl ThreadSafeRepository {
         mut worktree_dir: Option<PathBuf>,
         options: Options,
     ) -> Result<Self, Error> {
+        let _span = gix_trace::detail!("open_from_paths()");
         let Options {
             git_dir_trust,
             object_store_slots,
@@ -238,6 +241,7 @@ impl ThreadSafeRepository {
         refs.write_reflog = config::cache::util::reflog_or_default(config.reflog, worktree_dir.is_some());
         let replacements = replacement_objects_refs_prefix(&config.resolved, lenient_config, filter_config_section)?
             .and_then(|prefix| {
+                let _span = gix_trace::detail!("find replacement objects");
                 let platform = refs.iter().ok()?;
                 let iter = platform.prefixed(&prefix).ok()?;
                 let prefix = prefix.to_str()?;

gix/src/open/repository.rs

@@ -78,6 +78,7 @@ where
         P: Progress,
         P::SubProgress: 'static,
     {
+        let _span = gix_trace::coarse!("fetch::Prepare::receive()");
         let mut con = self.con.take().expect("receive() can only be called once");
 
         let handshake = &self.ref_map.handshake;
@@ -115,6 +116,7 @@ where
             });
         }
 
+        let negotiate_span = gix_trace::detail!("negotiate");
         let mut negotiator = repo
             .config
             .resolved
@@ -217,6 +219,8 @@ where
                 };
                 let graph = graph.detach();
                 drop(graph_repo);
+                drop(negotiate_span);
+
                 let previous_response = previous_response.expect("knowledge of a pack means a response was received");
                 if !previous_response.shallow_updates().is_empty() && shallow_lock.is_none() {
                     let reject_shallow_remote = repo

gix/src/remote/connection/fetch/receive_pack.rs

@@ -53,6 +53,7 @@ pub(crate) fn update(
     dry_run: fetch::DryRun,
     write_packed_refs: fetch::WritePackedRefs,
 ) -> Result<update::Outcome, update::Error> {
+    let _span = gix_trace::detail!("update_refs()");
     let mut edits = Vec::new();
     let mut updates = Vec::new();