update

Author: robelator

ARTICLE.md

@@ -1,12 +1,12 @@
-# The Ultimate Guide to `df_log`: Go Beyond `print()` in Flutter
+## Tired of `print()`? A Pragmatic Guide to Better Logging in Flutter.
 
-### A beginner-friendly tutorial and complete reference manual for making your Flutter debugging, analytics, and crash reporting smarter.
+### An honest, beginner-friendly look at `df_log` — a package that aims to make your console debugging, analytics, and crash reporting smarter, not just more complicated.
 
-![](https://raw.githubusercontent.com/dev-cetera/df_log/main/example/example.png)
+![Screenshot of df_log output in a terminal](https://raw.githubusercontent.com/dev-cetera/df_log/main/example/example.png)
 
-If you're a Flutter developer, your journey probably started with `print()`. It’s our oldest and most reliable friend for debugging. We sprinkle it everywhere to check a variable's value, confirm a function was called, or see if a widget rebuilt.
+If you're a Flutter developer, your journey started with `print()`. It’s our oldest friend for debugging. We sprinkle it everywhere to check a variable, confirm a function was called, or see if a widget rebuilt.
 
-But let's be honest. As our apps grow, the console becomes a chaotic wall of white text.
+But as our apps grow, the console becomes a chaotic, colorless waterfall of text.
 
 ```
 Button tapped
@@ -16,40 +16,25 @@ Network error
 UI updated
 ```
 
-You're left asking: _Which_ button was tapped? _Where_ did the network error happen? This ambiguity is where we waste precious time.
+You're left asking: *Which* button was tapped? *Where* did that network error happen? This ambiguity is where we waste precious time.
 
-What if your logs could be smart, organized, beautiful, and tell you _exactly_ where they came from? What if they could power your analytics and crash reporting automatically?
+Of course, there are powerful, "correct" ways to debug. The **Flutter Debugger** is an incredible tool that lets you pause your app with breakpoints, inspect the entire state, and step through code line by line. For complex bug hunting, it’s unbeatable.
 
-Meet **[df_log](https://pub.dev/packages/df_log)**, a simple but profoundly powerful logging package for Dart and Flutter. This guide will take you from a complete beginner to a master of `df_log`, showing you how it will fundamentally change the way you build and debug your apps.
+So, why talk about another logging package?
 
----
-
-### Part 1: Your First Steps - The 5-Minute Upgrade
-
-Let’s get you started. The initial payoff is immediate.
+Because sometimes, you don’t want to pause your app. You just want to watch the story of your code unfold in the console. You want the simplicity of `print()` but with more clarity, context, and control. What if your logs could also power your analytics and crash reporting automatically?
 
-#### Installation
+Meet **[df_log](https://pub.dev/packages/df_log)**, a pragmatic, opinionated tool designed to do one thing well: **make your console output beautiful, readable, and powerful.**
 
-1.  Open your `pubspec.yaml` file.
-2.  Add `df_log` to your dependencies:
-
-    ```yaml
-    dependencies:
-      flutter:
-        sdk: flutter
-      df_log: ^latest_version # Check pub.dev for the latest version
-    ```
+---
 
-3.  Run `flutter pub get` in your terminal.
-4.  Import the package in any Dart file where you want to log:
+### Part 1: Your First Steps - The 5-Minute Upgrade
 
-    ```dart
-    import 'package:df_log/df_log.dart';
-    ```
+The initial payoff is immediate. After adding `df_log` to your `pubspec.yaml` and importing it, you can immediately upgrade your `print()` statements.
 
 #### Your First "Smart" Log
 
-Now, replace a `print()` statement with a `df_log` equivalent.
+Replace a `print()` statement with a `df_log` equivalent.
 
 **Before:**
 
@@ -60,17 +45,19 @@ print('User successfully authenticated.');
 **After:**
 
 ```dart
+import 'package:df_log/df_log.dart';
+
 Log.ok('User successfully authenticated.');
 ```
 
 Run your app and look at the console. Instead of plain text, you’ll see something like this:
 
-`🟢 [lib/data/auth_repository.dart:42] User successfully authenticated.`
+`🟢 [auth_service/authenticateUser #42] User successfully authenticated.`
 
 This is the first "Aha!" moment. You instantly get three upgrades:
 
 1.  **A Category Icon (`🟢`):** You can tell at a glance that this was a success.
-2.  **The Exact Location:** You know this log came from `auth_repository.dart` on line `42`. No more guessing! You can click this in most IDEs to jump straight to the code.
+2.  **Precise Context `[filename/member #linenumber]`:** You know exactly where this log came from: the `authenticateUser` function inside the `auth_service.dart` file, on line `42`. No more guessing! You can click this in most IDEs to jump straight to the code.
 3.  **Color:** In supported consoles, the output is beautifully colored, making it easy to scan.
 
 You’ve already saved yourself minutes of future debugging time.
@@ -83,7 +70,7 @@ Now let's explore the foundational features that make `df_log` so effective.
 
 #### 1. Semantic Logging: Speaking with Intent
 
-`df_log` provides methods for different kinds of events. This gives your logs meaning.
+`df_log` provides methods for different kinds of events. This gives your logs meaning and turns your console into a readable story of your app's execution.
 
 ```dart
 void main() {
@@ -96,8 +83,6 @@ void main() {
 }
 ```
 
-This turns your console into a readable story of your app's execution, not just a random list of events.
-
 #### 2. Precision Filtering with Tags
 
 This is arguably the most powerful debugging feature. You can assign tags to your logs and then filter the console to show only what you need.
@@ -110,15 +95,12 @@ Let’s see it in action.
 // main.dart
 void main() {
   // Let's say we only want to debug the UI for the authentication flow.
-  Log.addTags({#ui, #auth});
+  Log.activeTags = {#ui, #auth};
 
   // ✅ Printed! Has the #auth tag, which is active.
   Log.ok('User logged in.', {#auth});
 
-  // ✅ Printed! Has the #ui tag, which is active.
-  Log.info('Rendering profile screen...', {#ui});
-
-  // ❌ NOT Printed! It requires the #network tag, which we haven't activated.
+  // ❌ NOT Printed! It requires the #network tag, which we haven't activated yet.
   Log.trace('Fetching user avatar...', {#ui, #network});
 
   // --- Now, let's debug the network call for the avatar ---
@@ -137,11 +119,11 @@ With tags, you can silence the noise from every other part of your app and focus
 
 This is where `df_log` transcends being just a logger. Using callbacks, you can turn it into a central event bus for your entire application.
 
-The `Log.addCallback()` method lets you execute a function every single time a log is created, giving you access to the complete `LogItem` object (message, tags, timestamp, etc.).
+The `Log.addCallback()` method lets you execute a function every single time a log is created, giving you access to the complete `LogItem` object.
 
 #### Use Case 1: Smarter Crash Reporting with Breadcrumbs
 
-When a crash happens, the error message is only half the story. The other half is _what the user did right before it_. `df_log` can automatically provide this context.
+When a crash happens, the error message is only half the story. The other half is *what the user did right before it*. `df_log` can automatically provide this context.
 
 ```dart
 // In your main.dart
@@ -157,7 +139,7 @@ void main() {
       // Get the history of recent events.
       final breadcrumbs = Log.items.map((item) => item.toMap()).toList();
 
-      // Send the error and the breadcrumbs to your reporting service.
+      // Send the error and the breadcrumbs to your reporting service (e.g., Sentry).
       MyCrashReporter.captureException(
         exception: logItem.message,
         extraData: {'log_breadcrumbs': breadcrumbs},
@@ -172,7 +154,6 @@ void main() {
 void updateUserProfile() {
   Log.info('Navigated to profile screen.', {#ui, #profile});
   try {
-    // ... code that might fail ...
     throw Exception('Connection timed out');
   } catch (e) {
     // This single line now does two things:
@@ -194,7 +175,11 @@ void setupAnalytics() {
     if (logItem.tags.contains(#analytics_event)) {
       // The log message can be the event name!
       final eventName = logItem.message.toString();
-      MyAnalyticsService.logEvent(name: eventName);
+      // The LogItem can be converted to a map for parameters.
+      final parameters = logItem.toMap();
+      
+      // Send to your service, e.g., Google Analytics / Firebase
+      FirebaseAnalytics.instance.logEvent(name: eventName, parameters: parameters);
     }
   });
 }
@@ -208,62 +193,61 @@ void onPurchaseButtonPressed() {
 }
 ```
 
-If you ever change your analytics provider, you only have to update one callback function, not hundreds of files. Your code becomes cleaner and completely decoupled from the analytics implementation.
+If you ever change your analytics provider, you only have to update **one callback function**, not hundreds of files. Your code becomes cleaner and completely decoupled from the analytics implementation.
 
 ---
 
-### Part 4: The Official `df_log` Manual (API Reference)
+### Part 4: The `df_log` Manual (Full Feature Set)
 
-Here is a quick reference to all the main features available in `df_log`.
+Here is a quick reference to all the main features available.
 
 #### Main Logging Methods
 
-- `Log.info(message, [tags])`: For general informational messages. (`🟣`)
-- `Log.ok(message, [tags])`: For success operations. (`🟢`)
-- `Log.err(message, [tags])`: For errors or exceptions. (`🔴`)
-- `Log.alert(message, [tags])`: For warnings that need attention. (`🟠`)
-- `Log.start(message, [tags])`: To mark the beginning of a process. (`🔵`)
-- `Log.stop(message, [tags])`: To mark the end of a process. (`⚫`)
-- `Log.trace(message, [tags])`: For fine-grained debugging information. (`⚪️`)
-- `Log.printGreen(message)`: Prints a message in a specific color without any other formatting. Many other colors are available (`printRed`, `printYellow`, etc.).
+-   `Log.info(msg, [tags])`: For general informational messages. (`🟣`)
+-   `Log.ok(msg, [tags])`: For success operations. (`🟢`)
+-   `Log.err(msg, [tags])`: For errors or exceptions. (`🔴`)
+-   `Log.alert(msg, [tags])`: For warnings that need attention. (`🟠`)
+-   `Log.start(msg, [tags])`: To mark the beginning of a process. (`🔵`)
+-   `Log.stop(msg, [tags])`: To mark the end of a process. (`⚫`)
+-   `Log.trace(msg, [tags])`: For fine-grained debugging information. (`⚪️`)
+-   `Log.printGreen(message)`: Prints a message in a specific color without any other formatting. Many other colors are available (`printRed`, `printYellow`, `printBlue`, etc.).
 
 #### Configuration (Static Properties on `Log`)
 
-- `Log.enableStyling = true`: Enables/disables ANSI colors and icons. Set to `false` if your console doesn't support them.
-- `Log.showTimestamps = true`: Shows a `HH:mm:ss.SSS` timestamp on each log.
-- `Log.showTags = true`: Shows tags like `#auth #ui` on each log.
-- `Log.showIds = false`: Shows a unique ID on each log.
-- `Log.enableReleaseAsserts = false`: By default, logs only work in debug mode. Set this to `true` to enable logging and asserts in release builds (use with caution).
+-   `Log.enableStyling = true`: Enables/disables ANSI colors and icons.
+-   `Log.showTimestamps = true`: Shows a `HH:mm:ss.SSS` timestamp on each log.
+-   `Log.showTags = true`: Shows tags like `#auth #ui` on each log.
+-   `Log.showIds = false`: Shows a unique ID on each log.
+-   `Log.enableReleaseAsserts = false`: By default, logs only work in debug mode. Set to `true` to enable logging in release builds (use with caution).
 
-#### In-Memory Storage
+#### In-Memory Storage & Callbacks
 
-- `Log.storeLogs = true`: If `true`, keeps a history of logs in memory.
-- `Log.maxStoredLogs = 1000`: Sets the maximum number of `LogItem` objects to store in the queue.
-- `Log.items`: A `Queue<LogItem>` containing the stored logs. You can access it directly to inspect history.
+-   `Log.storeLogs = true`: If `true`, keeps a history of logs in memory.
+-   `Log.maxStoredLogs = 1000`: Sets the max number of `LogItem` objects to store.
+-   `Log.items`: A `Queue<LogItem>` containing the stored logs.
+-   `Log.addCallback(callback)`: Registers a function `void Function(LogItem item)` that runs for every log.
+-   `Log.removeCallback(callback)`: Removes a previously registered callback.
 
-#### Tag Management
+#### Advanced Output
 
-- `Log.activeTags`: A `Set<Symbol>` of all currently active tags.
-- `Log.addTags(Set<Symbol> tags)`: Adds one or more tags to the active set.
-- `Log.removeTags(Set<Symbol> tags)`: Removes tags from the active set.
+-   `Log.useDeveloperLog()`: Switches output to `dart:developer`'s `log` function for a richer experience in some IDEs.
+-   `Log.useStandardPrint()`: Reverts the output to the standard `print` function.
 
-#### Advanced Features
+---
 
-- `Log.addCallback(callback)`: Registers a function `void Function(LogItem item)` that is called every time a log is created. Returns the callback so you can remove it later.
-- `Log.removeCallback(callback)`: Removes a previously registered callback.
-- `Log.useDeveloperLog()`: Switches the output to `dart:developer`'s `log` function, which can provide a richer experience in IDEs like VS Code's Debug Console.
-- `Log.useStandardPrint()`: Reverts the output to the standard `print` function.
+### Final Thoughts: Is This For You?
 
----
+Let’s be clear to pre-emptively address the critics. `df_log` is not trying to be the most powerful logging framework in the world.
+
+-   If you need advanced features like log rotation, writing to files, or complex custom formatters, a package like `logger` or `floggy` might be a better choice.
+-   If you are deep in a bug and need to inspect object properties and the call stack, **use the Flutter Debugger**. It is the right tool for that job.
 
-### Conclusion
+So, who is `df_log` for?
 
-`df_log` is more than just a pretty logger. It's a complete instrumentation framework that encourages you to treat events in your app as structured data. By adopting it, you get:
+It’s for the developer who finds themselves littering their code with `print('--- HERE 1 ---')` and wishes it was just a little bit… better. It’s for adding semantic, colorful, filterable breadcrumbs to trace the flow of an application. It's for centralizing your app's event-based logic, like analytics and crash reporting, through a single, clean API.
 
-- **Clarity:** Know exactly where every log comes from.
-- **Organization:** Use categories and tags to make your console readable and filterable.
-- **Power:** Use callbacks to drive crash reporting, analytics, and performance monitoring from a single, clean source of truth.
+The goal is to be **pragmatic**: to provide a massive step up from `print()` without the cognitive overhead of a full-fledged logging framework. It's a simple tool for a common, multifaceted problem.
 
-It's a small change to your workflow that pays massive dividends in productivity and code quality.
+If that sounds like something that could clean up your debug console and your codebase, give it a try.
 
-This is an open-source project actively maintained by **[Robert Mollentze](https://github.com/robert-mollentze)** and contributors. If you find it valuable, give the [GitHub repo](https://github.com/dev-cetera/df_log) a star, and consider [buying the author a coffee](https://www.buymeacoffee.com/dev_cetera) to support future development. Happy logging!
+This is an open-source project. If you find it valuable, give the [**GitHub repo**](https://github.com/dev-cetera/df_log) a star, and consider [**buying the author a coffee**](https://www.buymeacoffee.com/dev_cetera) to support future development. Happy logging

DEVELOPER_NOTES.md

@@ -558,6 +558,7 @@ final class Log {
 
     // Only print if combinedTags is empty or all of combinedTags are in activeTags.
     if (combinedTags.isNotEmpty && !activeTags.containsAll(combinedTags)) {
+      // TODO: Or just use contains?
       return;
     }
 

lib/src/log.dart

@@ -18,7 +18,7 @@ funding:
 - https://www.patreon.com/c/RobertMollentze
 - https://github.com/sponsors/robmllze
 description: A package that provides logging utilities for better debugging.
-version: 0.3.20
+version: 0.3.21
 topics:
   - console
   - debugging