feat: Request/Response Logging for Debugging

[kioku]

Summary

Implement debug logging for HTTP requests and responses to aid troubleshooting API issues.

Context

Currently, when an API call fails or returns unexpected data, users have limited visibility into what was actually sent/received. The --dry-run flag shows the request that would be made, but doesn't help debug actual execution.

Proposed Implementation

Environment Variable Control

# Enable debug logging
APERTURE_LOG=debug aperture api myapi users get-user --id 123

# Verbose mode (includes response bodies)
APERTURE_LOG=trace aperture api myapi users get-user --id 123

Log Levels

Level	Output
error	Only errors (default)
warn	Errors + warnings
info	+ Request summaries (method, URL, status, duration)
debug	+ Request/response headers
trace	+ Request/response bodies (truncated)

Output Format

info level:

→ GET https://api.example.com/users/123
← 200 OK (143ms)

debug level:

→ GET https://api.example.com/users/123
  Headers:
    Authorization: Bearer [REDACTED]
    Content-Type: application/json
    User-Agent: aperture/0.1.6
← 200 OK (143ms)
  Headers:
    Content-Type: application/json
    X-Request-Id: abc-123

trace level:

→ GET https://api.example.com/users/123
  Headers:
    Authorization: Bearer [REDACTED]
    Content-Type: application/json
  Body: (none)
← 200 OK (143ms)
  Headers:
    Content-Type: application/json
  Body: {"id": "123", "name": "Alice", ...} (truncated at 1000 chars)

Security Considerations

Always redact:

• Authorization header values → Bearer [REDACTED]
• API keys in query strings → ?api_key=[REDACTED]
• Secrets matching configured x-aperture-secret env vars

Truncation:

• Response bodies truncated at 1000 chars by default
• Configurable via APERTURE_LOG_MAX_BODY=5000

CLI Flag Alternative

# Equivalent to APERTURE_LOG=debug
aperture api myapi users get-user --id 123 --verbose

# Equivalent to APERTURE_LOG=trace
aperture api myapi users get-user --id 123 -vv

Log Destination

• Default: stderr (keeps stdout clean for piping)
• File output: APERTURE_LOG_FILE=/path/to/debug.log

Structured Logging Option

For programmatic log processing:

APERTURE_LOG=debug APERTURE_LOG_FORMAT=json aperture api myapi users get-user --id 123

{"level":"info","target":"aperture::executor","message":"request","method":"GET","url":"https://api.example.com/users/123","timestamp":"2024-01-15T10:30:00Z"}
{"level":"info","target":"aperture::executor","message":"response","status":200,"duration_ms":143,"timestamp":"2024-01-15T10:30:00Z"}

Implementation Notes

Consider using the tracing crate ecosystem:

• tracing for instrumentation
• tracing-subscriber for output formatting
• Already commonly used in async Rust projects

Acceptance Criteria

• APERTURE_LOG environment variable (error/warn/info/debug/trace)
• --verbose / -v flag (debug level)
• -vv flag (trace level)
• Request logging: method, URL, headers (debug+)
• Response logging: status, duration, headers (debug+)
• Body logging at trace level with truncation
• Automatic secret redaction
• Log to stderr by default
• APERTURE_LOG_FILE for file output
• APERTURE_LOG_FORMAT=json for structured logs
• Documentation for debugging workflows

Dependencies

• tracing crate
• tracing-subscriber crate