Skip to content

Consider JSON as default format for @ capturing operator #66

@willibrandon

Description

@willibrandon

Description:
Consider making JSON the default output format when using the @ capturing operator to align with modern Serilog behavior and structured logging expectations.

Background:
Currently, the @ operator produces Go's default struct format (%+v), which outputs:

&{AsepritePath:/path/to/aseprite TempDir:/tmp Timeout:30s LogLevel:debug}

To get JSON output, users must explicitly specify the :j format:

logger.Debug("Config: {@Config:j}", cfg)
// Output: {"aseprite_path":"/path/to/aseprite","temp_dir":"/tmp","timeout":30000000000,"log_level":"debug"}

Proposed Change:
Make @ produce JSON by default, with an option to get Go format:

logger.Debug("Config: {@Config}", cfg)    // JSON output (new default)
logger.Debug("Config: {@Config:go}", cfg) // Go struct format (opt-in)

Rationale:

  1. Serilog Alignment: Modern Serilog outputs structured/JSON representation when using @ with structured sinks
  2. Structured Logging: JSON is the de facto standard for structured logging, making logs more parseable
  3. Consistency: The @ operator's purpose is to create structured representations suitable for serialization
  4. User Expectations: Users coming from Serilog expect @ to produce structured output, not language-specific formatting

Current Workarounds:

  • Users must remember to add :j to every @ usage for structured output
  • Or accept Go's struct format which includes pointer notation (&{...})

Migration Path:
Since we're pre-v1.0, this change can be made directly. Users who prefer the Go format could:

  1. Use a new :go format specifier
  2. Use $ for scalar rendering
  3. Configure behavior globally via mtlog.WithGoCapturing() (optional)

Comparison with Other Libraries:

  • Serilog (.NET): @ produces structured output (JSON in structured sinks)
  • Zap (Go): Uses JSON by default for structured fields
  • Zerolog (Go): JSON-first design
  • slog (Go stdlib): JSON handler outputs JSON for structured data

Implementation Notes:

  • The change would be in the capturing/rendering logic
  • Would need to handle circular references in JSON serialization
  • Consider performance impact of JSON encoding vs fmt.Sprintf("%+v")
  • May want to pretty-print for console sinks vs compact for file/network sinks

Metadata

Metadata

Assignees

Labels

enhancementNew feature or request

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions