Skip to content

feat: add tracing instrumentation for command execution#242

Open
joshrotenberg wants to merge 1 commit intomainfrom
feat/tracing-instrumentation
Open

feat: add tracing instrumentation for command execution#242
joshrotenberg wants to merge 1 commit intomainfrom
feat/tracing-instrumentation

Conversation

@joshrotenberg
Copy link
Copy Markdown
Owner

Summary

Adds rich tracing spans and events to every Docker command execution path, behind an optional (default-on) tracing feature.

  • Top-level docker.command info span on CommandExecutor::execute_command with fields command, args_count, platform, runtime, timeout_secs. Because every DockerCommand::execute impl (regular, compose, buildx, swarm, manifest, generic) funnels through this method, all paths are instrumented automatically.
  • info! on success with duration_ms, exit_code, stdout_len, stderr_len.
  • warn! on non-zero exit / spawn failure with exit_code, duration_ms, error, plus a 512-byte UTF-8-safe truncated stderr_snippet.
  • Streaming variants wrapped in a docker.stream span (mode = handler or channel); each stdout/stderr line emits debug! so noisy builds can be filtered at the subscriber level.
  • New tracing cargo feature enabled by default. cargo build --no-default-features still compiles -- existing use tracing::*; sites go through a small internal tracing_compat shim that re-exports the real macros when the feature is on and expands to no-ops otherwise. #[instrument(...)] attributes are gated with cfg_attr.
  • README gains a Tracing section documenting span names, fields, and RUST_LOG recipes.

Closes #241

Test plan

  • cargo fmt --all -- --check
  • cargo clippy --all-targets --all-features -- -D warnings
  • cargo clippy --all-targets --no-default-features -- -D warnings
  • cargo test --lib --all-features (768 passed)
  • cargo test --lib --no-default-features (519 passed)
  • cargo test --doc --all-features (408 passed)
  • New tests/tracing_instrumentation.rs exercises span name, args_count field, and warn-on-failure event using tracing-test (gated behind the tracing feature, no Docker daemon required)
  • Pre-existing integration tests that require a running Docker daemon were not re-run -- they fail in this sandbox due to no local daemon, not due to changes in this PR

Wraps `DockerCommand::execute`, `StreamableCommand::stream`, and the compose,
buildx, and swarm paths (all of which funnel through `CommandExecutor::execute_command`)
in a top-level `docker.command` info span carrying `command`, `args_count`,
`platform`, `runtime`, and `timeout_secs` fields. Successful exits emit
`info!` with `duration_ms` + `exit_code`; non-zero exits emit `warn!` with
the same plus a 512-byte truncated stderr snippet.

Streaming variants run under a `docker.stream` span and emit `debug!` per
stdout/stderr line so noisy paths can be filtered at the subscriber level.

Instrumentation is gated behind a new `tracing` cargo feature, enabled by
default. Building with `--no-default-features` drops the `tracing`
dependency entirely; the existing `use tracing::*;` sites now go through a
small internal `tracing_compat` shim that re-exports the real macros when
the feature is on and expands to no-ops otherwise.

Closes #241
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add tracing instrumentation for command execution

1 participant