Strategic Logger

███████████████████████████████████████████████████████████████████
█          ___ _____ ___    _ _____ ___ ___ ___ ___               █
█         / __|_   _| _ \  /_\_   _| __/ __|_ _/ __|              █
█         \__ \ | | |   / / _ \| | | _| (_ || | (__               █
█         |___/ |_| |_|_\/_/ \_\_| |___\___|___\___|              █
█            / /   / __ \/ ____/ ____/ ____/ __ \                 █
█           / /   / / / / / __/ / __/ __/ / /_/ /                 █
█          / /___/ /_/ / /_/ / /_/ / /___/ _, _/                  █
█         /_____/\____/\____/\____/_____/_/ |_|                   █
█                                                                 █
█          🚀 Powered by Hypn Tech (hypn.com.br)                  █
███████████████████████████████████████████████████████████████████

---

---

✨ Why Strategic Logger?

🤖 MCP-Native Integration

• Model Context Protocol support for AI agent integration
• Native MCP server with HTTP endpoints for log querying
• Real-time log streaming to AI agents and tools
• Structured context for intelligent log analysis

🧠 AI-Powered Intelligence

• Intelligent log analysis with pattern detection
• Automated insights and recommendations
• Anomaly detection for proactive monitoring
• Smart log summarization for faster debugging

⚡ Performance First

• Isolate-based processing - Never block the main thread
• Async queue with backpressure - Handle high log volumes efficiently
• Object pooling - Optimized memory management
• Log compression - Reduce network and storage overhead

🎯 One Call, All Strategies

Log once and send to multiple destinations simultaneously - Console, Firebase, Sentry, Datadog, New Relic, MCP, and AI analysis.

🎨 Beautiful Console Output

• Modern formatting with colors, emojis, and structured layout
• Rich context display with metadata and stack traces
• Timestamp precision with millisecond accuracy

🔄 Drop-in Replacement

100% compatible with popular logger packages - no code changes required!

---

🚀 Quick Start

Installation

Add Strategic Logger to your pubspec.yaml:

dependencies:
  strategic_logger: ^1.3.0

Then run:

flutter pub get

Basic Usage

import 'package:strategic_logger/strategic_logger.dart';

void main() async {
  // Initialize once at app startup
  await logger.initialize(
    level: LogLevel.debug,
        strategies: [
      ConsoleLogStrategy(
        useModernFormatting: true,
        useColors: true,
        useEmojis: true,
      ),
      // MCP Strategy for AI agent integration
      MCPLogStrategy(port: 3000),
      // AI Strategy for intelligent analysis
      AILogStrategy(),
      // Traditional strategies
            FirebaseAnalyticsLogStrategy(),
            FirebaseCrashlyticsLogStrategy(),
        ],
    useIsolates: true,
    enablePerformanceMonitoring: true,
  );

  // Start logging!
  await logger.info('App started successfully');
  await logger.error('Something went wrong', stackTrace: StackTrace.current);
}

---

🎯 Features

🤖 MCP (Model Context Protocol) Features

• Native MCP Server - Built-in HTTP server for AI agent integration
• Real-time Log Streaming - Stream logs directly to AI agents and tools
• Structured Context API - Rich metadata for intelligent log analysis
• Health Monitoring - Built-in health endpoints and metrics
• Query Interface - Advanced log querying with filtering and search
• WebSocket Support - Real-time bidirectional communication

🧠 AI-Powered Features

• Intelligent Log Analysis - Automated pattern detection and anomaly identification
• Smart Insights - AI-generated recommendations and actionable insights
• Automated Summarization - Intelligent log summarization for faster debugging
• Predictive Analytics - Proactive monitoring with predictive insights
• Context-Aware Processing - AI understands log context and relationships
• Natural Language Queries - Query logs using natural language

🔧 Core Features

• Multiple Log Strategies - Console, Firebase, Sentry, Datadog, New Relic, MCP, AI
• Custom Strategies - Extend with your own logging destinations
• Log Levels - Debug, Info, Warning, Error, Fatal with intelligent routing
• Structured Logging - Rich metadata and context support
• Error Handling - Robust error management with predefined types

🚀 Performance Features

• Isolate Processing - Heavy operations run in background isolates
• Object Pooling - Optimized memory management for high-performance apps
• Log Compression - Intelligent compression to reduce network and storage overhead
• Performance Monitoring - Built-in metrics and performance tracking
• Async Queue - Efficient log processing with backpressure control
• Batch Processing - Automatic batching for network strategies
• Retry Logic - Exponential backoff for failed operations

🎨 Developer Experience

• Modern Console - Beautiful, colorful, emoji-rich output
• Compatibility Layer - Drop-in replacement for popular logger packages
• Type Safety - Full TypeScript-style type safety in Dart
• Hot Reload - Seamless development experience with Flutter
• Documentation - Comprehensive API documentation and examples

---

🤖 MCP (Model Context Protocol) Integration

Strategic Logger is the first logging framework to natively support the Model Context Protocol, enabling seamless integration with AI agents and intelligent tools.

MCP Server Features

// Initialize MCP strategy
final mcpStrategy = MCPLogStrategy(
  port: 3000,
  host: 'localhost',
  maxHistorySize: 10000,
);

// Start the MCP server
await mcpStrategy.startServer();

// Log with MCP context
await mcpStrategy.info(
  message: 'User authentication successful',
  context: {
    'userId': '12345',
    'sessionId': 'abc-def-ghi',
    'timestamp': DateTime.now().toIso8601String(),
  },
);

// Get health status
final health = await mcpStrategy.getHealthStatus();
print('MCP Server Health: $health');

AI Agent Integration

// Initialize AI strategy for intelligent analysis
final aiStrategy = AILogStrategy(
  analysisInterval: Duration(minutes: 5),
  batchSize: 100,
  enableInsights: true,
);

// Start AI analysis
await aiStrategy.startAnalysis();

// Log with AI context
await aiStrategy.error(
  message: 'Database connection failed',
  context: {
    'database': 'users_db',
    'retryCount': 3,
    'lastError': 'Connection timeout',
  },
);

// Generate intelligent summary
final summary = await aiStrategy.generateLogSummary();
print('AI Analysis: $summary');

MCP Endpoints

The MCP server provides several HTTP endpoints for AI agent integration:

• GET /health - Server health and metrics
• GET /logs - Retrieve recent logs with filtering
• POST /query - Advanced log querying
• WebSocket /stream - Real-time log streaming

---

📖 Usage Examples

🚀 Basic Logging

import 'package:strategic_logger/logger.dart';

// Initialize logger
await logger.initialize(
  strategies: [
    ConsoleLogStrategy(
      useModernFormatting: true,
      useColors: true,
      useEmojis: true,
    ),
  ],
  enablePerformanceMonitoring: true,
);

// Basic logging
await logger.debug('Debug message');
await logger.info('Info message');
await logger.warning('Warning message');
await logger.error('Error message');
await logger.fatal('Fatal error');

🎯 Structured Logging with Context

// Rich context logging
await logger.info('User action', context: {
  'userId': '123',
  'action': 'login',
  'timestamp': DateTime.now().toIso8601String(),
  'device': 'iPhone 15',
  'version': '1.2.3',
});

// Error with stack trace
try {
  // Some risky operation
  throw Exception('Something went wrong');
} catch (e, stackTrace) {
  await logger.error('Operation failed', context: {
    'operation': 'data_sync',
    'error': e.toString(),
  });
}

🔥 Multi-Strategy Logging

// Log to multiple destinations simultaneously
await logger.initialize(
  strategies: [
    ConsoleLogStrategy(useModernFormatting: true),
    SentryLogStrategy(dsn: 'your-sentry-dsn'),
    FirebaseCrashlyticsLogStrategy(),
    DatadogLogStrategy(apiKey: 'your-api-key'),
    MCPLogStrategy(), // AI agent integration
    AILogStrategy(apiKey: 'your-openai-key'),
  ],
);

// One call, multiple destinations
await logger.error('Critical system failure', context: {
  'component': 'payment_service',
  'severity': 'critical',
});

🤖 AI-Powered Log Analysis

// Enable AI analysis for intelligent insights
final aiStrategy = AILogStrategy(
  apiKey: 'your-openai-api-key',
  analysisInterval: Duration(minutes: 5),
);

await logger.initialize(
  strategies: [aiStrategy],
);

// AI will automatically analyze patterns and provide insights
await logger.info('High memory usage detected', context: {
  'memory_usage': '85%',
  'threshold': '80%',
});

🔄 Real-time Log Streaming

// Listen to real-time log events
logger.logStream.listen((logEntry) {
  print('New log: ${logEntry.level} - ${logEntry.message}');
  
  // Update UI, send to external systems, etc.
  updateDashboard(logEntry);
});

// Logs will automatically appear in the stream
await logger.info('User performed action');

📱 Flutter App Integration

class MyApp extends StatefulWidget {
  @override
  _MyAppState createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> {
  @override
  void initState() {
    super.initState();
    _initializeLogger();
  }

  Future<void> _initializeLogger() async {
    await logger.initialize(
      strategies: [
        ConsoleLogStrategy(useModernFormatting: true),
        FirebaseCrashlyticsLogStrategy(),
      ],
      enablePerformanceMonitoring: true,
    );
    
    logger.info('App initialized successfully');
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        body: Center(
          child: ElevatedButton(
            onPressed: () async {
              await logger.info('Button pressed', context: {
                'screen': 'home',
                'timestamp': DateTime.now().toIso8601String(),
              });
            },
            child: Text('Log Action'),
          ),
        ),
      ),
    );
  }
}

🔧 Advanced Configuration

// Custom configuration with all features
await logger.initialize(
  strategies: [
    ConsoleLogStrategy(
      useModernFormatting: true,
      useColors: true,
      useEmojis: true,
      showTimestamp: true,
      showContext: true,
    ),
    SentryLogStrategy(
      dsn: 'your-sentry-dsn',
      environment: 'production',
    ),
    DatadogLogStrategy(
      apiKey: 'your-datadog-api-key',
      site: 'datadoghq.com',
      service: 'my-flutter-app',
    ),
  ],
  level: LogLevel.info,
  useIsolates: true, // Enable isolate-based processing
  enablePerformanceMonitoring: true,
  enableModernConsole: true,
);

// Performance monitoring
final stats = logger.getPerformanceStats();
print('Logs processed: ${stats['totalLogs']}');
print('Average processing time: ${stats['avgProcessingTime']}ms');

// Force flush all queued logs
await logger.flush();

🔄 Drop-in Replacement (Compatibility)

// 100% compatible with popular logger packages
logger.debugSync('Debug message');
logger.infoSync('Info message');
logger.errorSync('Error message');

// Or use the compatibility extension
loggerCompatibility.debug('Debug message');
loggerCompatibility.info('Info message');
loggerCompatibility.error('Error message');

### Object Pooling & Memory Optimization

```dart
// Initialize object pool for memory optimization
final objectPool = ObjectPool();
await objectPool.initialize();

// Get pooled objects (automatically managed)
final logEntry = objectPool.getLogEntry();
final context = objectPool.getContextMap();

// Use objects...
logEntry.message = 'Optimized logging';
context['userId'] = '12345';

// Return to pool (automatic cleanup)
objectPool.returnLogEntry(logEntry);
objectPool.returnContextMap(context);

// Get pool statistics
final poolStats = objectPool.getStats();
print('Pool Stats: $poolStats');

Log Compression

// Initialize log compression
final compression = LogCompression();
await compression.startCompression();

// Add logs for compression
for (int i = 0; i < 1000; i++) {
  await compression.addLogEntry(CompressibleLogEntry(
    message: 'Log entry $i',
    level: LogLevel.info,
    timestamp: DateTime.now(),
    context: {'iteration': i},
  ));
}

// Get compression statistics
final compressionStats = compression.getStats();
print('Compression Stats: $compressionStats');

---

🎨 Modern Console Output

Experience beautiful, structured console output:

🐛 14:30:25.123 DEBUG  User action completed
📋 Event: USER_ACTION
   Message: User completed purchase
   Parameters:
     userId: 123
     amount: 99.99
🔍 Context:
   timestamp: 2024-01-15T14:30:25.123Z
   source: mobile_app

---

🔧 Configuration

Advanced Initialization

await logger.initialize(
  level: LogLevel.info,
  strategies: [
    // Console with modern formatting
    ConsoleLogStrategy(
      useModernFormatting: true,
      useColors: true,
      useEmojis: true,
      showTimestamp: true,
      showContext: true,
    ),
    
    // Firebase Analytics
    FirebaseAnalyticsLogStrategy(),
    
    // Firebase Crashlytics
    FirebaseCrashlyticsLogStrategy(),
    
    // Datadog
    DatadogLogStrategy(
      apiKey: 'your-datadog-api-key',
      service: 'my-app',
      env: 'production',
      tags: 'team:mobile,version:1.0.0',
    ),
    
    // New Relic
    NewRelicLogStrategy(
      licenseKey: 'your-newrelic-license-key',
      appName: 'my-app',
      environment: 'production',
    ),
  ],
  
  // Modern features
  useIsolates: true,
  enablePerformanceMonitoring: true,
  enableModernConsole: true,
);

Custom Strategies

Create your own logging strategy:

class MyCustomLogStrategy extends LogStrategy {
    @override
  Future<void> log({dynamic message, LogEvent? event}) async {
    // Use isolates for heavy processing
    final result = await isolateManager.executeInIsolate(
      'customTask',
      {'message': message, 'event': event?.toMap()},
    );
    
    // Send to your custom service
    await _sendToCustomService(result);
  }
  
  @override
  Future<void> info({dynamic message, LogEvent? event}) async {
    await log(message: message, event: event);
  }
  
  @override
  Future<void> error({dynamic error, StackTrace? stackTrace, LogEvent? event}) async {
    await log(message: error, event: event);
  }
  
  @override
  Future<void> fatal({dynamic error, StackTrace? stackTrace, LogEvent? event}) async {
    await log(message: error, event: event);
    }
}

---

📊 Performance

Strategic Logger is designed for high performance:

• Isolate-based processing prevents blocking the main thread
• Automatic batching reduces network overhead
• Async queue with backpressure handles high log volumes
• Performance monitoring tracks operation metrics
• Efficient serialization minimizes memory usage

Performance Metrics

final stats = logger.getPerformanceStats();
print('Total operations: ${stats['processLogEntry']?.totalOperations}');
print('Average duration: ${stats['processLogEntry']?.averageDuration}ms');
print('Error rate: ${stats['processLogEntry']?.errorRate}%');

---

🆕 Migration Guide

From v0.1.x to v0.2.x

The new version introduces breaking changes for better performance and modern features:

// Old way (v0.1.x)
logger.initialize(
  level: LogLevel.info,
  strategies: [ConsoleLogStrategy()],
);

// New way (v0.2.x)
await logger.initialize(
  level: LogLevel.info,
  strategies: [
    ConsoleLogStrategy(
      useModernFormatting: true,
      useColors: true,
      useEmojis: true,
    ),
  ],
  useIsolates: true,
  enablePerformanceMonitoring: true,
  enableModernConsole: true,
);

---

🌐 Supported Platforms

• ✅ Flutter (iOS, Android, Web, Desktop)
• ✅ Dart CLI applications
• ✅ Dart VM applications
• ✅ Flutter Web
• ✅ Flutter Desktop (Windows, macOS, Linux)

---

🎯 Use Cases & Applications

🏢 Enterprise Applications

• Microservices Architecture - Centralized logging across distributed systems
• High-Traffic Applications - Handle millions of logs with isolate-based processing
• Real-time Monitoring - AI-powered anomaly detection and alerting
• Compliance & Auditing - Structured logging for regulatory requirements

🤖 AI & Machine Learning

• Model Context Protocol - Native integration with AI agents and tools
• Intelligent Log Analysis - Automated pattern detection and insights
• Predictive Monitoring - Proactive issue detection and prevention
• Natural Language Queries - Query logs using conversational AI

📱 Mobile & Flutter Applications

• Cross-Platform Logging - Consistent logging across iOS, Android, Web, Desktop
• Performance Optimization - Isolate-based processing for smooth UI
• Crash Analytics - Integration with Firebase Crashlytics and Sentry
• User Behavior Tracking - Structured logging for analytics

☁️ Cloud & DevOps

• Multi-Cloud Support - Datadog, New Relic, AWS CloudWatch integration
• Container Logging - Optimized for Docker and Kubernetes environments
• Serverless Functions - Efficient logging for Lambda and Cloud Functions
• CI/CD Integration - Automated testing and deployment logging

---

🗺️ Roadmap

🚀 v2.0.0 - AI-Powered Enterprise Features (Q2 2025)

• Advanced AI Integration - GPT-4, Claude integration
• Enterprise Observability - OpenTelemetry, distributed tracing
• Health Monitoring - Application health monitoring and alerts
• Smart Analysis - Automatic pattern detection and anomaly detection

🔧 v3.0.0 - Cloud Native & Ecosystem (Q3 2025)

• Grafana Integration - Custom dashboards and intelligent alerts
• Prometheus Integration - Detailed metrics and Kubernetes integration
• Developer Tools - VS Code extension and CLI tools
• Cloud Native - Kubernetes operator and Istio integration

🌐 v4.0.0 - AI-Powered Autonomous Logging (Q4 2025)

• AI Insights Engine - Predictive analysis and auto-healing
• Predictive Analytics - Failure prediction and optimization
• Auto-Healing - Automatic problem correction and prevention
• Strategy Marketplace - Third-party strategies and custom plugins

---

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Setup

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

💖 Support

If you find Strategic Logger helpful, please consider:

• ⭐ Starring the repository
• 🐛 Reporting bugs
• 💡 Suggesting new features
• 🤝 Contributing code
• ☕ Buy me a coffee

---

🏢 Sponsored by

---

📄 License

Strategic Logger is released under the MIT License. See LICENSE for details.

---

📚 Documentation & Resources

📖 Official Documentation

• API Documentation - Complete API reference
• Examples - Ready-to-use code examples
• Changelog - Version history and updates
• Contributing Guide - How to contribute to the project

🎓 Learning Resources

• MCP Integration Guide - Complete MCP setup and usage
• AI-Powered Logging - AI features and best practices
• Performance Optimization - Performance tuning guide
• Migration Guide - Upgrading from other loggers

🔧 Tools & Integrations

• VS Code Extension - IDE integration
• Flutter Inspector - Debug integration
• CI/CD Templates - GitHub Actions, GitLab CI examples
• Docker Images - Container deployment guide

🌟 Community

• GitHub Discussions - Community support
• Discord Server - Real-time chat
• Stack Overflow - Q&A support
• Reddit Community - Discussions and news

---