Skip to content

Add environment-based error display levels (prod/local/staging) #322

@RAprogramm

Description

@RAprogramm

Problem

Currently, Display implementation for Error shows either too little information (only kind without colored feature) or too much (everything including source chain, metadata, and potentially sensitive data with colored feature).

Production environments need:

  • Structured JSON logging for machine parsing (Datadog, Grafana, etc.)
  • Minimal, safe output without internal details
  • No colors (not needed for structured logs)

Development environments need:

  • Human-readable format with full context
  • Complete source chain and backtrace
  • Colored output (when colored feature is enabled and TTY is detected)

Proposed Solution

Implement environment-based display levels controlled by MASTERROR_ENV environment variable:

MASTERROR_ENV=prod (Production)

  • Lightweight JSON format
  • Fields: kind, code, message (if not redacted)
  • Filtered metadata (no sensitive fields)
  • NO source chain
  • NO backtrace
  • NO colors (JSON doesn't need coloring)

Example output:

{"kind":"NotFound","code":"NOT_FOUND","message":"User not found"}

MASTERROR_ENV=local (Development)

  • Human-readable format
  • Full source chain (all levels)
  • Complete metadata
  • Full backtrace (if backtrace feature enabled)
  • Colors if colored feature enabled AND TTY detected

Example output:

Error: NotFound
Code: NOT_FOUND
Message: User not found

  Caused by: database error
  Caused by: connection failed

Context:
  user_id: 12345

Backtrace:
  0: app::handlers::user at src/handlers.rs:42

MASTERROR_ENV=staging (Optional)

  • JSON format with additional context
  • Fields: kind, code, message, source_chain (limited depth), metadata
  • NO backtrace
  • NO colors

Example output:

{"kind":"NotFound","code":"NOT_FOUND","message":"User not found","source_chain":["database error","connection failed"],"metadata":{"user_id":12345}}

Requirements

  1. Separation of concerns:

    • MASTERROR_ENV controls structure and content
    • colored feature controls coloring only
    • TTY detection auto-disables colors for non-terminal output
  2. Auto-detection:

    • Default to prod if MASTERROR_ENV not set and !cfg!(debug_assertions)
    • Default to local if MASTERROR_ENV not set and cfg!(debug_assertions)
    • Detect Kubernetes environment (KUBERNETES_SERVICE_HOST) → force prod
  3. Performance:

    • Cache env variable check (use OnceLock or similar)
    • Zero-alloc JSON formatting where possible
    • No runtime overhead in hot paths
  4. Backward compatibility:

    • Existing colored feature behavior preserved
    • No breaking changes to public API
    • Default behavior should work for most users
  5. Security:

    • Respect MessageEditPolicy::Redact
    • Filter sensitive metadata fields in all modes
    • Never expose internal paths or backtraces in prod mode

Implementation Notes

  • Add new module src/app_error/display.rs for display formatting logic
  • Implement fmt_prod, fmt_local, fmt_staging methods
  • Modify Display trait implementation to dispatch based on environment
  • Add comprehensive tests for all display modes
  • Add doctests showing each mode

Testing

  • Unit tests for each display mode
  • Tests for env variable detection
  • Tests for TTY detection
  • Tests for metadata filtering in prod mode
  • Tests for colored output (when feature enabled)
  • Tests for security (no sensitive data leaks in prod)

Documentation

  • Document MASTERROR_ENV variable in README
  • Add examples for each mode
  • Migration guide for users (if needed)

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions