activity_logger

activity_logger is a lightweight, structured application activity logger for Flutter and Dart applications. It provides component-based log tagging, configurable log levels, production safety, and a clean sink output abstraction.

Features

• Structured Logging: Emit structured log events with consistent formatting.
• Component Identification: Tag log messages with service, repository, or class context (e.g., [SessionService]).
• Log Levels: Categorize messages using DEBUG, INFO, SUCCESS, WARNING, and ERROR.
• Timestamps: Local formatted timestamps ([HH:mm:ss]).
• Minimum Log-Level Filtering: Suppress low-priority log events automatically.
• Debug Mode Only: Suppress logs in production release builds using Flutter's kDebugMode.
• Global Configuration: Customize timestamps, tag visibility, log levels, and sinks at application startup.
• Custom Log Sinks: Route log events to console or custom destinations via LogSink.
• Console Output: Formatted stdout console sink out of the box (ConsoleLogSink).

Installation

Add activity_logger to your pubspec.yaml:

dependencies:
  activity_logger: ^0.1.0

Then run:

flutter pub get

or for pure Dart applications:

dart pub get

Quick Start

Import the package:

import 'package:activity_logger/activity_logger.dart';

Create a logger for a specific class or service context:

class SessionService {
  final ActivityLogger _log = const ActivityLogger('SessionService');

  void login() {
    _log.info('Login started');

    try {
      // Perform authentication...
      _log.success('Login successful');
    } catch (e, stackTrace) {
      _log.error('Authentication failed', error: e, stackTrace: stackTrace);
    }
  }
}

Log Levels

activity_logger defines five severity levels with increasing ordering:

LogLevel.debug < LogLevel.info < LogLevel.success < LogLevel.warning < LogLevel.error.

• LogLevel.debug: Fine-grained development information.
• LogLevel.info: General informational messages regarding application flow.
• LogLevel.success: Positive confirmations of completed actions.
• LogLevel.warning: Non-critical warnings or unexpected state changes.
• LogLevel.error: Critical errors, exceptions, or operation failures.

Configuration

Configure logger settings globally at application startup:

void main() {
  ActivityLogger.configure(
    enabled: true,
    debugModeOnly: true,
    minimumLogLevel: LogLevel.debug,
    showTimestamp: true,
    showClassName: true,
    sinks: [
      const ConsoleLogSink(),
    ],
  );

  runApp(const MyApp());
}

Output

Example console output when timestamp and class name formatting are enabled:

[14:32:45] [INFO] [SessionService] Login started
[14:32:45] [SUCCESS] [SessionService] Login successful
[14:32:46] [WARNING] [SessionService] Token is about to expire
[14:32:47] [ERROR] [SessionService] Login failed
Error: Exception: Invalid credentials
StackTrace: #0      main (package:example/main.dart:25)

Custom Sink

Create custom log sinks by implementing the LogSink interface:

class MemoryLogSink implements LogSink {
  final List<LogEntry> logs = [];

  @override
  void write(LogEntry entry) {
    logs.add(entry);
    // Custom storage, network forwarding, or telemetry logic
  }
}

Register your custom sink during configuration:

final memorySink = MemoryLogSink();

ActivityLogger.configure(
  sinks: [
    const ConsoleLogSink(),
    memorySink,
  ],
);

Design Philosophy

• Explicit Context over Anonymous Prints: Every log belongs to an identified component or domain.
• Structured Data Separated from Output: Log events are created as immutable LogEntry objects and dispatched cleanly to LogSink targets.
• Production Safety: Built-in release mode guarding prevents unintended log exposure.
• Zero Heavy Dependencies: Lightweight and fast with no third-party library bloat.

Roadmap

• x Initial release structure and configuration models (0.1.0).
• x Core log level ordering and severity comparison.
• x Immutable LogEntry data model and LogSink abstraction.
• x Built-in ConsoleLogSink with customizable output toggles.
• Dedicated file logging sink.
• Network telemetry / remote log sink integrations.

License

This project is licensed under the MIT License - see the LICENSE file for details.