Merge pull request #41 from theseus-rs/trace-instrumentation

feat: add tracing instrumentation

Author: brianheineman

Cargo.toml

@@ -13,33 +13,33 @@ repository = "https://github.com/theseus-rs/postgresql-embedded"
 version = "0.7.1"
 
 [workspace.dependencies]
-anyhow = { version = "1.0" }
-async-trait = { version = "0.1" }
-bytes = { version = "1.5" }
-criterion = { version = "0.5" }
-flate2 = { version = "1.0" }
-hex = { version = "0.4" }
-home = { version = "0.5" }
-human_bytes = { version = "0.4", default-features = false }
-lazy_static = { version = "1.4" }
-num-format = { version = "0.4" }
-rand = { version = "0.8" }
-regex = { version = "1.10" }
-reqwest = { version = "0.11", default-features = false, features = ["json", "rustls-tls-native-roots"] }
-reqwest-middleware = { version = "0.2.4" }
-reqwest-retry = { version = "0.4.0" }
-reqwest-tracing = { version = "0.4.0" }
-serde = { version = "1.0", features = ["derive"] }
-serde_json = { version = "1.0" }
-sha2 = { version = "0.10" }
-tar = { version = "0.4" }
-task-local-extensions = { version = "0.1" }
-target-triple = { version = "0.1" }
-test-log = { version = "0.2" }
-tempfile = { version = "3.10" }
-thiserror = { version = "1.0" }
-tokio = { version = "1.36", features = ["full"] }
-tracing = { version = "0.1", features = ["log"] }
+anyhow = "1.0.81"
+async-trait = "0.1.77"
+bytes = "1.5.0"
+criterion = "0.5.1"
+flate2 = "1.0.28"
+hex = "0.4.3"
+home = "0.5.9"
+human_bytes = { version = "0.4.3", default-features = false }
+lazy_static = "1.4.0"
+num-format = "0.4.4"
+rand = "0.8.5"
+regex = "1.10.3"
+reqwest = { version = "0.11.26", default-features = false }
+reqwest-middleware = "0.2.4"
+reqwest-retry = "0.4.0"
+reqwest-tracing = "0.4.0"
+serde = "1.0.197"
+serde_json = "1.0.114"
+sha2 = "0.10.8"
+tar = "0.4.40"
+task-local-extensions = "0.1.4"
+target-triple = "0.1.2"
+test-log = "0.2.15"
+tempfile = "3.10.1"
+thiserror = "1.0.58"
+tokio = "1.36.0"
+tracing = "0.1.40"
 
 [workspace.metadata.release]
 shared-version = true

examples/archive_async/Cargo.toml

@@ -8,4 +8,4 @@ version.workspace = true
 [dependencies]
 postgresql_archive = { path = "../../postgresql_archive" }
 tempfile = { workspace = true }
-tokio = { workspace = true }
+tokio = { workspace = true, features = ["full"] }

examples/embedded_async/Cargo.toml

@@ -7,4 +7,4 @@ version.workspace = true
 
 [dependencies]
 postgresql_embedded = { path = "../../postgresql_embedded" }
-tokio = { workspace = true }
+tokio = { workspace = true, features = ["full"] }

examples/postgres_embedded/Cargo.toml

@@ -7,5 +7,5 @@ version.workspace = true
 
 [dependencies]
 anyhow = { workspace = true }
-postgres = { version = "0.19" }
+postgres = { version = "0.19.7" }
 postgresql_embedded = { path = "../../postgresql_embedded", features = ["blocking"] }

examples/sqlx_embedded/Cargo.toml

@@ -8,5 +8,5 @@ version.workspace = true
 [dependencies]
 anyhow = { workspace = true }
 postgresql_embedded = { path = "../../postgresql_embedded" }
-sqlx = { version = "0.7", default-features = true, features = ["postgres", "runtime-tokio"] }
-tokio = { workspace = true }
+sqlx = { version = "0.7.4", default-features = true, features = ["postgres", "runtime-tokio"] }
+tokio = { workspace = true, features = ["full"] }

postgresql_archive/Cargo.toml

@@ -15,24 +15,24 @@ async-trait = { workspace = true }
 bytes = { workspace = true }
 flate2 = { workspace = true }
 hex = { workspace = true }
-human_bytes = { workspace = true }
+human_bytes = { workspace = true, default-features = false }
 lazy_static = { workspace = true }
 num-format = { workspace = true }
 regex = { workspace = true }
-reqwest = { workspace = true }
+reqwest = { workspace = true, default-features = false, features = ["json", "rustls-tls-native-roots"] }
 reqwest-middleware = { workspace = true }
 reqwest-retry = { workspace = true }
 reqwest-tracing = { workspace = true }
-serde = { workspace = true }
+serde = { workspace = true, features = ["derive"] }
 serde_json = { workspace = true }
 sha2 = { workspace = true }
 tar = { workspace = true }
 target-triple = { workspace = true }
 task-local-extensions = { workspace = true }
 tempfile = { workspace = true }
 thiserror = { workspace = true }
-tokio = { workspace = true, optional = true }
-tracing = { workspace = true }
+tokio = { workspace = true, features = ["full"], optional = true }
+tracing = { workspace = true, features = ["log"] }
 
 [dev-dependencies]
 criterion = { workspace = true }

postgresql_archive/src/archive.rs

@@ -25,7 +25,7 @@ use std::thread::sleep;
 use std::time::Duration;
 use tar::Archive;
 use task_local_extensions::Extensions;
-use tracing::{debug, warn};
+use tracing::{debug, instrument, warn};
 
 const GITHUB_API_VERSION_HEADER: &str = "X-GitHub-Api-Version";
 const GITHUB_API_VERSION: &str = "2022-11-28";
@@ -101,6 +101,7 @@ fn reqwest_client() -> ClientWithMiddleware {
 
 /// Gets a release from GitHub for a given [version](Version) of PostgreSQL. If a release for the
 /// [version](Version) is not found, then a [ReleaseNotFound] error is returned.
+#[instrument(level = "debug")]
 async fn get_release(version: &Version) -> Result<Release> {
     let url = "https://api.github.com/repos/theseus-rs/postgresql-binaries/releases";
     let client = reqwest_client();
@@ -169,6 +170,7 @@ async fn get_release(version: &Version) -> Result<Release> {
 /// Gets the version of PostgreSQL for the specified [version](Version).  If the version minor or release is not
 /// specified, then the latest version is returned. If a release for the [version](Version) is not found, then a
 /// [ReleaseNotFound] error is returned.
+#[instrument(level = "debug")]
 pub async fn get_version(version: &Version) -> Result<Version> {
     let release = get_release(version).await?;
     Version::from_str(&release.tag_name)
@@ -180,6 +182,7 @@ pub async fn get_version(version: &Version) -> Result<Version> {
 /// is not found, then an [error](crate::error::Error) is returned.
 ///
 /// Two assets are returned. The first [asset](Asset) is the archive, and the second [asset](Asset) is the archive hash.
+#[instrument(level = "debug", skip(target))]
 async fn get_asset<S: AsRef<str>>(version: &Version, target: S) -> Result<(Version, Asset, Asset)> {
     let release = get_release(version).await?;
     let asset_version = Version::from_str(&release.tag_name)?;
@@ -212,6 +215,7 @@ async fn get_asset<S: AsRef<str>>(version: &Version, target: S) -> Result<(Versi
 /// [error](crate::error::Error) is returned.
 ///
 /// Returns the archive version and bytes.
+#[instrument]
 pub async fn get_archive(version: &Version) -> Result<(Version, Bytes)> {
     get_archive_for_target(version, target_triple::TARGET).await
 }
@@ -222,6 +226,7 @@ pub async fn get_archive(version: &Version) -> Result<(Version, Bytes)> {
 /// is not found, then an [error](crate::error::Error) is returned.
 ///
 /// Returns the archive version and bytes.
+#[instrument(level = "debug", skip(target))]
 pub async fn get_archive_for_target<S: AsRef<str>>(
     version: &Version,
     target: S,
@@ -270,6 +275,7 @@ pub async fn get_archive_for_target<S: AsRef<str>>(
 
 /// Acquires a lock file in the [out_dir](Path) to prevent multiple processes from extracting the
 /// archive at the same time.
+#[instrument(level = "debug")]
 fn acquire_lock(out_dir: &Path) -> Result<PathBuf> {
     let lock_file = out_dir.join("postgresql-archive.lock");
 
@@ -313,6 +319,7 @@ fn acquire_lock(out_dir: &Path) -> Result<PathBuf> {
 }
 
 /// Extracts the compressed tar [bytes](Bytes) to the [out_dir](Path).
+#[instrument]
 pub async fn extract(bytes: &Bytes, out_dir: &Path) -> Result<()> {
     let input = BufReader::new(Cursor::new(bytes));
     let decoder = GzDecoder::new(input);

postgresql_embedded/Cargo.toml

@@ -13,7 +13,7 @@ version.workspace = true
 [build-dependencies]
 anyhow = { workspace = true }
 postgresql_archive = { path = "../postgresql_archive", version = "0.7.1" }
-tokio = { workspace = true }
+tokio = { workspace = true, features = ["full"] }
 
 [dependencies]
 anyhow = { workspace = true }
@@ -24,13 +24,13 @@ postgresql_archive = { path = "../postgresql_archive", version = "0.7.1" }
 rand = { workspace = true }
 tempfile = { workspace = true }
 thiserror = { workspace = true }
-tokio = { workspace = true, optional = true }
-tracing = { workspace = true }
+tokio = { workspace = true, features = ["full"], optional = true }
+tracing = { workspace = true, features = ["log"] }
 
 [dev-dependencies]
 criterion = { workspace = true }
 test-log = { workspace = true }
-tokio = { workspace = true }
+tokio = { workspace = true, features = ["full"] }
 
 [features]
 default = []

postgresql_embedded/src/command/traits.rs

@@ -1,11 +1,12 @@
 use crate::error::Result;
 use std::ffi::{OsStr, OsString};
+use std::fmt::Debug;
 use std::path::PathBuf;
 use std::time::Duration;
 use tracing::debug;
 
 /// Trait to build a command
-pub trait CommandBuilder {
+pub trait CommandBuilder: Debug {
     /// Get the program name
     fn get_program(&self) -> &'static OsStr;
 
@@ -151,6 +152,7 @@ mod test {
 
     #[test]
     fn test_command_builder_defaults() {
+        #[derive(Debug)]
         struct DefaultCommandBuilder {
             program_dir: Option<PathBuf>,
         }
@@ -171,6 +173,7 @@ mod test {
         assert_eq!(r#""test""#, command.to_command_string());
     }
 
+    #[derive(Debug)]
     struct TestCommandBuilder {
         program_dir: Option<PathBuf>,
         args: Vec<OsString>,

postgresql_embedded/src/postgresql.rs

@@ -15,7 +15,7 @@ use std::net::TcpListener;
 use std::ops::Deref;
 #[cfg(feature = "bundled")]
 use std::str::FromStr;
-use tracing::debug;
+use tracing::{debug, instrument};
 
 use crate::command::psql::PsqlBuilder;
 use crate::Error::{CreateDatabaseError, DatabaseExistsError, DropDatabaseError};
@@ -90,6 +90,7 @@ impl PostgreSQL {
     }
 
     /// Get the [status](Status) of the PostgreSQL server
+    #[instrument(level = "debug")]
     pub fn status(&self) -> Status {
         if self.is_running() {
             Status::Started
@@ -136,6 +137,7 @@ impl PostgreSQL {
     /// Set up the database by extracting the archive and initializing the database.
     /// If the installation directory already exists, the archive will not be extracted.
     /// If the data directory already exists, the database will not be initialized.
+    #[instrument]
     pub async fn setup(&mut self) -> Result<()> {
         if !self.is_installed() {
             self.install().await?;
@@ -153,6 +155,7 @@ impl PostgreSQL {
     /// hash does not match the expected hash, an error will be returned. If the installation directory
     /// already exists, the archive will not be extracted. If the archive is not found, an error will be
     /// returned.
+    #[instrument]
     async fn install(&mut self) -> Result<()> {
         debug!("Starting installation process for version {}", self.version);
 
@@ -201,6 +204,7 @@ impl PostgreSQL {
 
     /// Initialize the database in the data directory. This will create the necessary files and
     /// directories to start the database.
+    #[instrument]
     async fn initialize(&mut self) -> Result<()> {
         if !self.settings.password_file.exists() {
             let mut file = std::fs::File::create(&self.settings.password_file)?;
@@ -234,6 +238,7 @@ impl PostgreSQL {
 
     /// Start the database and wait for the startup to complete.
     /// If the port is set to `0`, the database will be started on a random port.
+    #[instrument]
     pub async fn start(&mut self) -> Result<()> {
         if self.settings.port == 0 {
             let listener = TcpListener::bind(("0.0.0.0", 0))?;
@@ -269,6 +274,7 @@ impl PostgreSQL {
     }
 
     /// Stop the database gracefully (smart mode) and wait for the shutdown to complete.
+    #[instrument]
     pub async fn stop(&self) -> Result<()> {
         debug!(
             "Stopping database {}",
@@ -294,6 +300,7 @@ impl PostgreSQL {
     }
 
     /// Create a new database with the given name.
+    #[instrument(skip(database_name))]
     pub async fn create_database<S: AsRef<str>>(&self, database_name: S) -> Result<()> {
         debug!(
             "Creating database {} for {}:{}",
@@ -327,6 +334,7 @@ impl PostgreSQL {
     }
 
     /// Check if a database with the given name exists.
+    #[instrument(skip(database_name))]
     pub async fn database_exists<S: AsRef<str>>(&self, database_name: S) -> Result<bool> {
         debug!(
             "Checking if database {} exists for {}:{}",
@@ -358,6 +366,7 @@ impl PostgreSQL {
     }
 
     /// Drop a database with the given name.
+    #[instrument(skip(database_name))]
     pub async fn drop_database<S: AsRef<str>>(&self, database_name: S) -> Result<()> {
         debug!(
             "Dropping database {} for {}:{}",
@@ -405,6 +414,7 @@ impl PostgreSQL {
 
     #[cfg(feature = "tokio")]
     /// Execute a command and return the stdout and stderr as strings.
+    #[instrument(level = "debug")]
     async fn execute_command<B: CommandBuilder>(
         &self,
         command_builder: B,