astute_logger 2.0.2

A simple and powerful logger for Flutter apps with support for color-coding, JSON pretty-printing, and performance tracking.

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

---

2.0.2 - 2024-12-10

📚 Documentation

• Enhanced README.md: Improved clarity, structure, and readability throughout
• Added badges: Pub version and license badges for better visibility
• Updated installation guide: Clear dependency instructions for path_provider and share_plus
• Refined code examples: Better quick start examples for common use cases
• Improved feature descriptions: More concise and scannable feature list
• Better formatting: Enhanced markdown formatting for improved readability

🔧 Improvements

• More comprehensive CHANGELOG documentation
• Clearer migration guides between versions
• Enhanced inline code examples in README

Note

This is a documentation-only release with no code changes. No action required for existing implementations.

---

2.0.1 2024-12-9

🐛 Bug Fixes

• Fixed dispose() race condition: Stream drain now properly waits for all queued events to be processed before closing file sink
• Improved error handling: Added guards around file write operations to prevent crashes when sink is closed
• Enhanced remote logging safety: Remote sender errors are now caught and logged without crashing the app

🔧 Improvements

• Better disposal lifecycle: Added _drainCompleter to ensure all logs are flushed before cleanup
• Timeout protection: Added 2-second timeout to dispose() to prevent infinite waits
• Enhanced error logging: File write and remote sender errors now log to console using dev.log()
• Stream subscription management: Proper subscription tracking with _subscription field
• Safer sink operations: Multiple try-catch blocks prevent IO errors from propagating

📚 Documentation

• Added comprehensive README.md for pub.dev
• Improved inline documentation for disposal and error handling
• Added migration guide for version transitions

🧹 Code Quality

• Better separation of concerns in _processEvent()
• Cleaner error recovery patterns
• More defensive programming around nullable sink operations

---

2.0.0 - 2024-12-08

🚀 New Features

• Caller location tracking: Automatically captures function name, file, and line number for each log
• Color-coded console output: Level-based ANSI colors (blue=DEBUG, green=INFO, yellow=WARNING, red=ERROR)
• Convenience logging methods: debug(), info(), warning(), error()
• Advanced sensitive-data redaction for:
  • password, token, access_token, refresh_token
  • Now supports both snake_case and camelCase variants
• Paginated log output: printLogsPaginated()
• Search logs by keywords: searchLogs()
• SharePlus v12 sharing API for log export
• Pretty JSON/log list formatting:
  • logJson()
  • logPrettyList()
• Execution time measurement: logExecutionTime()
• Safe remote logging pipeline with isolated error handling
• ANSI color-coded console output
• Raw JSON logging mode (no timestamp/caller prefix)
• Test-friendly directory provider: AstuteLogger.debugDirectoryProvider for mocking in tests

🔧 Improvements

• Rebuilt using a stream-driven asynchronous log queue
• Safer and more stable file IO using buffered IOSink
• Automatic ANSI stripping for file and remote logs
• Stronger, deterministic dispose() lifecycle handling
• Multiple crash-proof guards for file writing, sharing, and remote logging
• Timestamp and caller info now added in write() method for consistency
• Removed global logDecoration (simplified to color-based formatting)

🧪 Testing Enhancements

• AstuteLogger.consoleOverride enables deterministic log testing without touching dev.log()
• AstuteLogger.debugDirectoryProvider allows mocking file system in tests

🛡 Safety & Performance

• Redaction happens before enqueueing
• Queue drain ensured before shutdown
• Logs never block the UI thread
• Better error recovery for file operations

💥 Breaking Changes

• Removed logDecoration parameter: Decoration system replaced with automatic color coding
• Removed _decorate() method: Simplified to _colorize() for level-based coloring
• Changed log format: Now includes [timestamp] [level] [caller @ file:line] message
• logJson() behavior change: Now logs raw JSON without timestamp/caller prefix

📦 Dependencies

• Updated share_plus to v12.0.0
• Requires path_provider for file logging
• Requires path for path operations

---

1.1.0 - 2024-12-07

🎉 Major Update - Stable Release

This release represents a significant evolution of AstuteLogger with architectural improvements, new features, and enhanced capabilities.

✨ Added

New Logging Destinations

• File Logging: Persistent storage of logs (initFileLogging())
• Remote Logging: Callback-based remote forwarding (remoteSender)
• Multi-destination Support: Console + File + Remote

Enhanced Features

• Async Queue Processing via Dart Streams
• Tagged Logs using tag:
• Sensitive Data Redaction (password, token, access_token, refresh_token)
• ANSI Color Stripping for non-console logs
• Console Override for deterministic tests (consoleOverride)

Convenience Methods

• logWithColor()
• dispose() cleanup

Configuration

• Instance-level minLevel (removed in 2.0.0 redesign)
• enableFileLogging, enableRemote, fileNamePrefix

🔄 Changed

• Architecture upgraded to async-stream queue
• Release mode now disables logs automatically
• Buffered file IO for reliability

🔧 Technical Improvements

• Stronger regex redaction
• Better JSON parsing
• Stream lifecycle safety

📦 Dependencies

• path_provider
• path

🎯 Platform Support

• Android, iOS, Web, macOS, Windows, Linux

---

0.0.1 - 2024-11-25

🎉 Initial Release

• Basic console logging with ANSI colors
• Pretty JSON (logJson)
• Pretty list/map logging
• Execution timing (logExecutionTime)
• Build mode detection (debug/profile/release)
• Automatic method name detection (now removed in 2.0.0)

---

Migration Guide — 1.x → 2.0.0

🔥 Required Changes

1. File logging now requires explicit initialization

await logger.initFileLogging();

2. Log decoration removed

The logDecoration parameter has been removed. Logs now use automatic color coding based on level.

Before (1.x):

AstuteLogger.logDecoration = LogDecoration.singleBox;

After (2.0.0+):

// Colors are applied automatically - no configuration needed
logger.info('This will be green');
logger.error('This will be red');

3. Enhanced log format

Logs now include caller information automatically:

Before (1.x):

[2024-12-08 10:30:45] [INFO] User logged in

After (2.0.0+):

[2024-12-08 10:30:45] [INFO] [loginUser @ auth.dart:42] User logged in

---

Migration Guide — 2.0.0 → 2.0.1

No breaking changes. This is a bug fix release that improves disposal safety and error handling. Simply update your dependency version:

dependencies:
  astute_logger: ^2.0.1

If you were experiencing crashes during app shutdown or when disposing loggers, this update will resolve those issues.