[wirwolf]

This PR introduces a comprehensive logging system to vault-manager, replacing ad-hoc debug output with structured, configurable diagnostic logging.

Summary

Adds a new logging package that provides structured logging via Go's standard log/slog library, with support for multiple log levels (error, warn, info, debug, trace) and output formats (text, JSON). Logging is written to stderr by default, keeping stdout clean for command output and scripting. The system integrates throughout the codebase to provide diagnostic information at appropriate verbosity levels.

Key Changes

• New logging package (logging/logging.go):

  • ParseLevel() and ParseFormat() for configuration validation
  • New() to create configured loggers
  • Setup() to handle legacy DEBUG environment variable with deprecation warning
  • LevelTrace constant for sub-debug verbosity with HTTP tracing
  • Stable attribute keys (KeyCommand, KeyPath, KeyCount, etc.) for consistent logging

• HTTP tracing (vault/trace.go):

  • tracingTransport middleware logs HTTP method, redacted URL, status, and duration at trace level
  • RedactURL() strips user info and masks sensitive query parameters (token, secret, password, etc.)
  • Never logs request/response bodies or headers containing secrets

• Command-line integration:

  • New --log-level and --log-format flags in cmd/options.go
  • Environment variables VAULT_MANAGER_LOG_LEVEL and VAULT_MANAGER_LOG_FORMAT
  • Flags take precedence over environment variables
  • ExpandFlagAssignments() handles --flag=value syntax

• Vault client logging (vault/vault.go):

  • Accepts optional Logger in VaultConfig
  • Logs configuration at debug level
  • Integrates HTTP tracing transport

• Sync operations logging (vaultsync/plan.go, pull.go, apply.go):

  • Plan: logs stages, paths, and change counts without secret values
  • Pull: logs per-secret decisions and sync summary
  • Apply: logs applied changes and confirmations
  • All accept optional logger parameter

• Runner logging (app/runner.go):

  • Logs command lifecycle (start, completion, failures) at debug level
  • Includes command name and argument count (never argument values)
  • Tracks error types (usage vs runtime)

• Documentation:

  • Updated README with logging configuration table and examples
  • Added "Diagnostics" section to sync documentation
  • Updated command reference with global options
  • Docker documentation includes logging environment variables

Notable Implementation Details

• Loggers are never nil; OrDiscard() provides a no-op logger when needed
• Secret values are never logged; only paths, counts, and metadata
• Trace level is below debug (-8) to enable HTTP request tracing
• LevelTrace is rendered as "TRACE" in output via replaceLevelName() attribute handler
• Legacy DEBUG=1 environment variable maps to trace level with deprecation warning
• All logging is opt-in; commands remain silent at default info level

https://claude.ai/code/session_016mgmWtAUXMBCJLCHSP2bjZ