feat: add structured logging instrumentation for step-level operations

josecelano · josecelano · commit b5bcf8f775a8 · 2025-09-16T17:58:21.000+01:00
- Add #[instrument] to infrastructure steps:
  * InitializeInfrastructureStep with initialize_infrastructure span
  * PlanInfrastructureStep with plan_infrastructure span
  * ApplyInfrastructureStep with apply_infrastructure span (includes auto_approve field)
  * GetInstanceInfoStep with get_instance_info span

- Add #[instrument] to rendering steps:
  * RenderOpenTofuTemplatesStep with render_opentofu_templates span
  * RenderAnsibleTemplatesStep with render_ansible_templates span

- Add #[instrument] to system, connectivity, software, and validation steps:
  * WaitForCloudInitStep with wait_cloud_init span
  * WaitForSSHConnectivityStep with wait_ssh_connectivity span
  * InstallDockerStep with install_docker span
  * InstallDockerComposeStep with install_docker_compose span
  * ValidateCloudInitCompletionStep with validate_cloud_init span
  * ValidateDockerInstallationStep with validate_docker span
  * ValidateDockerComposeInstallationStep with validate_docker_compose span

This implements Phase 2 of the structured logging plan, creating complete
two-level hierarchical spans (Commands → Steps) with consistent naming
conventions and contextual fields following the plan specifications.
diff --git a/src/steps/connectivity/wait_ssh_connectivity.rs b/src/steps/connectivity/wait_ssh_connectivity.rs
@@ -1,4 +1,4 @@
-use tracing::info;
+use tracing::{info, instrument};
 
 use crate::command_wrappers::ssh::{SshClient, SshConnection, SshError};
 
@@ -24,6 +24,11 @@ impl WaitForSSHConnectivityStep {
     /// * SSH connectivity cannot be established within the timeout period
     /// * The SSH client fails to initialize
     /// * The SSH command execution fails
+    #[instrument(
+        name = "wait_ssh_connectivity",
+        skip_all,
+        fields(step_type = "connectivity", protocol = "ssh")
+    )]
     pub async fn execute(&self) -> Result<(), SshError> {
         info!(
             step = "wait_ssh_connectivity",
diff --git a/src/steps/infrastructure/apply.rs b/src/steps/infrastructure/apply.rs
@@ -1,6 +1,6 @@
 use std::sync::Arc;
 
-use tracing::info;
+use tracing::{info, instrument};
 
 use crate::command::CommandError;
 use crate::command_wrappers::opentofu::client::OpenTofuClient;
@@ -34,6 +34,15 @@ impl ApplyInfrastructureStep {
     /// * The `OpenTofu` apply fails
     /// * The working directory does not exist or is not accessible
     /// * The `OpenTofu` command execution fails
+    #[instrument(
+        name = "apply_infrastructure",
+        skip_all,
+        fields(
+            step_type = "infrastructure",
+            operation = "apply",
+            auto_approve = %self.auto_approve
+        )
+    )]
     pub fn execute(&self) -> Result<(), CommandError> {
         info!(
             step = "apply_infrastructure",
diff --git a/src/steps/infrastructure/get_instance_info.rs b/src/steps/infrastructure/get_instance_info.rs
@@ -1,6 +1,6 @@
 use std::sync::Arc;
 
-use tracing::info;
+use tracing::{info, instrument};
 
 use crate::command_wrappers::opentofu::client::{InstanceInfo, OpenTofuClient, OpenTofuError};
 
@@ -28,6 +28,11 @@ impl GetInstanceInfoStep {
     /// * The output cannot be parsed as JSON
     /// * The `instance_info` section is missing or malformed
     /// * The working directory does not exist or is not accessible
+    #[instrument(
+        name = "get_instance_info",
+        skip_all,
+        fields(step_type = "infrastructure", operation = "info")
+    )]
     pub fn execute(&self) -> Result<InstanceInfo, OpenTofuError> {
         info!(
             step = "get_instance_info",
diff --git a/src/steps/infrastructure/initialize.rs b/src/steps/infrastructure/initialize.rs
@@ -1,6 +1,6 @@
 use std::sync::Arc;
 
-use tracing::info;
+use tracing::{info, instrument};
 
 use crate::command::CommandError;
 use crate::command_wrappers::opentofu::client::OpenTofuClient;
@@ -24,6 +24,11 @@ impl InitializeInfrastructureStep {
     /// * The `OpenTofu` initialization fails
     /// * The working directory does not exist or is not accessible
     /// * The `OpenTofu` command execution fails
+    #[instrument(
+        name = "initialize_infrastructure",
+        skip_all,
+        fields(step_type = "infrastructure", operation = "init")
+    )]
     pub fn execute(&self) -> Result<(), CommandError> {
         info!(
             step = "initialize_infrastructure",
diff --git a/src/steps/infrastructure/plan.rs b/src/steps/infrastructure/plan.rs
@@ -1,6 +1,6 @@
 use std::sync::Arc;
 
-use tracing::info;
+use tracing::{info, instrument};
 
 use crate::command::CommandError;
 use crate::command_wrappers::opentofu::client::OpenTofuClient;
@@ -24,6 +24,11 @@ impl PlanInfrastructureStep {
     /// * The `OpenTofu` plan fails
     /// * The working directory does not exist or is not accessible
     /// * The `OpenTofu` command execution fails
+    #[instrument(
+        name = "plan_infrastructure",
+        skip_all,
+        fields(step_type = "infrastructure", operation = "plan")
+    )]
     pub fn execute(&self) -> Result<(), CommandError> {
         info!(
             step = "plan_infrastructure",
diff --git a/src/steps/rendering/ansible_templates.rs b/src/steps/rendering/ansible_templates.rs
@@ -3,7 +3,7 @@ use std::path::PathBuf;
 use std::sync::Arc;
 
 use thiserror::Error;
-use tracing::info;
+use tracing::{info, instrument};
 
 use crate::ansible::template_renderer::ConfigurationTemplateError;
 use crate::ansible::AnsibleTemplateRenderer;
@@ -54,6 +54,11 @@ impl RenderAnsibleTemplatesStep {
     ///
     /// Returns an error if the template rendering fails or if there are issues
     /// with the template manager or renderer.
+    #[instrument(
+        name = "render_ansible_templates",
+        skip_all,
+        fields(step_type = "rendering", template_type = "ansible")
+    )]
     pub async fn execute(&self) -> Result<(), RenderAnsibleTemplatesError> {
         info!(
             step = "render_ansible_templates",
diff --git a/src/steps/rendering/opentofu_templates.rs b/src/steps/rendering/opentofu_templates.rs
@@ -1,6 +1,6 @@
 use std::sync::Arc;
 
-use tracing::info;
+use tracing::{info, instrument};
 
 use crate::tofu::template_renderer::{ProvisionTemplateError, TofuTemplateRenderer};
 
@@ -23,6 +23,11 @@ impl RenderOpenTofuTemplatesStep {
     ///
     /// Returns an error if the template rendering fails or if there are issues
     /// with the template manager or renderer.
+    #[instrument(
+        name = "render_opentofu_templates",
+        skip_all,
+        fields(step_type = "rendering", template_type = "opentofu")
+    )]
     pub async fn execute(&self) -> Result<(), ProvisionTemplateError> {
         info!(
             step = "render_opentofu_templates",
diff --git a/src/steps/software/docker.rs b/src/steps/software/docker.rs
@@ -1,5 +1,5 @@
 use std::sync::Arc;
-use tracing::info;
+use tracing::{info, instrument};
 
 use crate::command::CommandError;
 use crate::command_wrappers::ansible::AnsibleClient;
@@ -32,6 +32,11 @@ impl InstallDockerStep {
     /// - The install-docker playbook assumes the apt cache is already updated
     ///   or will handle stale cache gracefully
     /// - We skip the update-apt-cache playbook in E2E tests to avoid CI network issues
+    #[instrument(
+        name = "install_docker",
+        skip_all,
+        fields(step_type = "software", component = "docker", method = "ansible")
+    )]
     pub fn execute(&self) -> Result<(), CommandError> {
         info!(
             step = "install_docker",
diff --git a/src/steps/software/docker_compose.rs b/src/steps/software/docker_compose.rs
@@ -1,5 +1,5 @@
 use std::sync::Arc;
-use tracing::info;
+use tracing::{info, instrument};
 
 use crate::command::CommandError;
 use crate::command_wrappers::ansible::AnsibleClient;
@@ -26,6 +26,15 @@ impl InstallDockerComposeStep {
     /// * The Ansible client fails to execute the playbook
     /// * Docker Compose installation fails
     /// * The playbook execution fails for any other reason
+    #[instrument(
+        name = "install_docker_compose",
+        skip_all,
+        fields(
+            step_type = "software",
+            component = "docker_compose",
+            method = "ansible"
+        )
+    )]
     pub fn execute(&self) -> Result<(), CommandError> {
         info!(
             step = "install_docker_compose",
diff --git a/src/steps/system/wait_cloud_init.rs b/src/steps/system/wait_cloud_init.rs
@@ -1,5 +1,5 @@
 use std::sync::Arc;
-use tracing::info;
+use tracing::{info, instrument};
 
 use crate::command::CommandError;
 use crate::command_wrappers::ansible::AnsibleClient;
@@ -26,6 +26,11 @@ impl WaitForCloudInitStep {
     /// * The Ansible client fails to execute the playbook
     /// * Cloud-init has not completed within the timeout period
     /// * The playbook execution fails for any other reason
+    #[instrument(
+        name = "wait_cloud_init",
+        skip_all,
+        fields(step_type = "system", component = "cloud_init")
+    )]
     pub fn execute(&self) -> Result<(), CommandError> {
         info!(
             step = "wait_cloud_init",
diff --git a/src/steps/validation/cloud_init.rs b/src/steps/validation/cloud_init.rs
@@ -1,4 +1,4 @@
-use tracing::info;
+use tracing::{info, instrument};
 
 use crate::command_wrappers::ssh::SshConnection;
 use crate::remote_actions::{CloudInitValidator, RemoteAction, RemoteActionError};
@@ -31,6 +31,11 @@ impl ValidateCloudInitCompletionStep {
     /// - This validation ensures that all cloud-init modules have completed
     /// - Critical for ensuring the system is ready for further configuration
     /// - Checks both cloud-init status and completion markers
+    #[instrument(
+        name = "validate_cloud_init",
+        skip_all,
+        fields(step_type = "validation", component = "cloud_init")
+    )]
     pub async fn execute(&self) -> Result<(), RemoteActionError> {
         info!(component = "cloud_init", "Validating cloud-init completion");
 
diff --git a/src/steps/validation/docker.rs b/src/steps/validation/docker.rs
@@ -1,4 +1,4 @@
-use tracing::info;
+use tracing::{info, instrument};
 
 use crate::command_wrappers::ssh::SshConnection;
 use crate::remote_actions::{DockerValidator, RemoteAction, RemoteActionError};
@@ -31,6 +31,11 @@ impl ValidateDockerInstallationStep {
     /// - In CI environments with network limitations, Docker installation
     ///   validation may be skipped gracefully
     /// - The validation checks both Docker version and daemon status
+    #[instrument(
+        name = "validate_docker",
+        skip_all,
+        fields(step_type = "validation", component = "docker")
+    )]
     pub async fn execute(&self) -> Result<(), RemoteActionError> {
         info!(component = "docker", "Validating Docker installation");
 
diff --git a/src/steps/validation/docker_compose.rs b/src/steps/validation/docker_compose.rs
@@ -1,4 +1,4 @@
-use tracing::info;
+use tracing::{info, instrument};
 
 use crate::command_wrappers::ssh::SshConnection;
 use crate::remote_actions::{DockerComposeValidator, RemoteAction, RemoteActionError};
@@ -31,6 +31,11 @@ impl ValidateDockerComposeInstallationStep {
     /// - In CI environments with network limitations, Docker Compose installation
     ///   validation may be skipped gracefully
     /// - The validation checks Docker Compose version and availability
+    #[instrument(
+        name = "validate_docker_compose",
+        skip_all,
+        fields(step_type = "validation", component = "docker_compose")
+    )]
     pub async fn execute(&self) -> Result<(), RemoteActionError> {
         info!(
             component = "docker_compose",
