logs_spotter

A powerful and secure logging solution for Flutter applications with optional remote storage on Supabase.

---

📋 Table of Contents

• Features
• Installation
• Supabase Setup
• Quick Start
• Usage
• API Reference
• Migration Guide
• Contributing
• License

✨ Features

• 🔐 Secure: AES-256-CBC encryption for remote logs
• 📱 Multi-Platform: Works on Android, iOS, Web, Desktop
• 💾 Flexible Storage:
  • Console output for development
  • Local file storage for offline access
  • Remote storage via Supabase with encryption
• 🎯 Simple API: Intuitive extension methods for logging
• 👤 User Tracking: Built-in user labeling for debugging
• ⚡ Lightweight: Minimal dependencies, maximum performance
• 🔄 Automatic Error Capture: Integration with Flutter's error handling
• 🏷️ Log Levels: Fine, Info, and Error levels with visual indicators
• 🌐 Open Source: MIT licensed, community-driven

📦 Installation

Add logs_spotter to your pubspec.yaml:

dependencies:
  logs_spotter: ^0.1.4

Then run:

flutter pub get

🔧 Supabase Setup

To enable remote logging, you need to set up a Supabase project:

1. Create a Supabase Project

1. Go to supabase.com and create a free account
2. Create a new project
3. Wait for the project to be ready

2. Create the Inspector Table

Go to the SQL Editor in your Supabase dashboard and run this query:

CREATE TABLE inspector (
  id BIGSERIAL PRIMARY KEY,
  message TEXT NOT NULL,
  level TEXT NOT NULL,
  origin TEXT,
  "user" TEXT,
  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

3. Get Your Credentials

From your Supabase project settings:

• Project URL: Settings → API → Project URL
• Anon Key: Settings → API → Project API keys → anon public

4. (Optional) Enable Row Level Security

For production, you may want to add RLS policies:

-- Enable RLS
ALTER TABLE inspector ENABLE ROW LEVEL SECURITY;

-- Example: Allow all authenticated users to insert
CREATE POLICY "Allow authenticated inserts" ON inspector
  FOR INSERT
  TO authenticated
  WITH CHECK (true);

-- Example: Allow service role to read all
CREATE POLICY "Allow service role to read" ON inspector
  FOR SELECT
  TO service_role
  USING (true);

🚀 Quick Start

Basic Setup

import 'package:flutter/material.dart';
import 'package:logs_spotter/logs_spotter.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // Initialize Spotter with Supabase
  Spotter.initialize(
    'https://your-project.supabase.co',
    'your-anon-key-here',
  );

  // Optional: Set user identifier for tracking
  Spotter.set_UserLabel('user-123');

  // Wrap runApp to catch Flutter errors automatically
  await spotterScope(() async {
    runApp(const MyApp());
  });
}

Start Logging

// Success/confirmation logs ✅
"User logged in successfully".f(origin: "AuthService");

// Information logs ⚠️
"Loading user data...".i(origin: "UserRepository");

// Error logs 🚨
"Failed to fetch data".e(origin: "ApiClient");

// Without origin
"Simple log message".f();
"Another message".i();

📚 Usage

Log Levels

logs_spotter provides three log levels with visual indicators:

Method	Level	Icon	Use Case	Example
.f()	Fine	✅	Success, confirmations, debug info	"Data saved".f()
.i()	Info	⚠️	General information, user actions	"Button clicked".i()
.e()	Error	🚨	Errors, exceptions, failures	"Network error".e()

Advanced Configuration

Spotter.initialize(
  'https://your-project.supabase.co',
  'your-anon-key',
);

User Tracking

Track logs by user to help with debugging user-specific issues:

// Set user label (e.g., user ID, email, session ID)
Spotter.set_UserLabel('user_$userId');

// Logs will now include this user identifier
"Action performed".i(origin: "UserDashboard");

Error Catching

Wrap your app in spotterScope to automatically catch and log Flutter errors:

await spotterScope(() async {
  runApp(const MyApp());
});

This will capture:

• Flutter framework errors
• Unhandled exceptions
• Widget build errors

With Origin Tagging

Use the origin parameter to identify where logs come from:

class MyService {
  void performAction() {
    "Starting action".i(origin: "MyService");
    
    try {
      // ... your code
      "Action completed".f(origin: "MyService");
    } catch (e) {
      "Action failed: $e".e(origin: "MyService");
    }
  }
}

📖 API Reference

Initialization

void Spotter.initialize(String url, String anonKey)

Parameters:

• url: Your Supabase project URL
• anonKey: Your Supabase anon/public key

User Management

// Set user identifier
void Spotter.set_UserLabel(String userId)

// Get current user label
String? Spotter.getUserLabel()

Logging Methods

// Fine level (✅ success/debug)
extension on String {
  void f({String? origin})
}

// Info level (⚠️ information)
extension on String {
  void i({String? origin})
}

// Error level (🚨 errors)
extension on String {
  void e({String? origin})
}

Error Handling

// Wrap your app to catch errors
Future<void> spotterScope(Future<void> Function() callback)

🔄 Migration Guide

Migrating from Firebase (v0.1.x)

If you're upgrading from the Firebase version, please see the detailed MIGRATION.md guide.

Key Changes:

• Firebase dependencies removed → Supabase integration
• initializeEngine() → Spotter.initialize()
• .spot() → Direct methods .f(), .i(), .e()
• tag parameter → origin parameter
• All remote logs are now encrypted with AES-256-CBC

🔒 Security

Encryption

All logs sent to Supabase are encrypted using AES-256-CBC encryption:

• Encryption Key: Derived from your Supabase anon key using SHA-256
• Initialization Vector: Randomly generated for each log entry
• Algorithm: AES-256-CBC (industry standard)
• Storage: Encrypted messages are stored in Supabase, decryption key stays with you

This ensures that even if someone gains access to your Supabase database, they cannot read your logs without your anon key.

Best Practices

1. Never commit credentials: Use environment variables or secure config files
2. Rotate keys regularly: Update your Supabase anon key periodically
3. Use RLS policies: Enable Row Level Security in Supabase for production
4. Limit log content: Avoid logging sensitive user data (passwords, tokens, etc.)
5. Monitor access: Regularly review who has access to your Supabase project

🎯 Use Cases

Development & Debugging

• Track user flows and interactions
• Debug production issues with encrypted logs
• Monitor app performance

Production Monitoring

• Collect crash reports automatically
• Track user-specific issues
• Analyze error patterns

Team Collaboration

• Share logs across team members
• Maintain searchable log history
• Filter by user, level, or origin

📊 Example Output

Console Output

✅ [Fine] User logged in successfully | Origin: AuthService | User: user-123
⚠️ [Info] Loading user data... | Origin: UserRepository | User: user-123
🚨 [Error] Network timeout | Origin: ApiClient | User: user-123

Supabase Table

id	message (encrypted)	level	origin	user	created_at
1	U2FsdGVkX1...	fine	AuthService	user-123	2025-01-15 10:30:00
2	U2FsdGVkX1...	info	UserRepository	user-123	2025-01-15 10:30:05
3	U2FsdGVkX1...	error	ApiClient	user-123	2025-01-15 10:30:10

💡 Tips & Tricks

Development vs Production

// Use different configs for dev/prod
final isProduction = const bool.fromEnvironment('dart.vm.product');

Spotter.initialize(
  isProduction ? prodUrl : devUrl,
  isProduction ? prodKey : devKey,
);

Filter Logs in Supabase

-- Get all errors from the last hour
SELECT * FROM inspector 
WHERE level = 'error' 
  AND created_at > NOW() - INTERVAL '1 hour'
ORDER BY created_at DESC;

-- Get logs for a specific user
SELECT * FROM inspector 
WHERE "user" = 'user-123'
ORDER BY created_at DESC
LIMIT 100;

-- Get logs by origin
SELECT * FROM inspector 
WHERE origin = 'AuthService'
ORDER BY created_at DESC;

🤝 Contributing

Contributions are welcome! Here's how you can help:

1. Report bugs: Open an issue with details and reproduction steps
2. Suggest features: Share your ideas for improvements
3. Submit PRs: Fix bugs or add features (please discuss first for large changes)
4. Improve docs: Help make the documentation better
5. Share feedback: Let us know how you're using logs_spotter

Please read CONTRIBUTING.md for details on our code of conduct and the process for submitting pull requests.

📝 Changelog

See CHANGELOG.md for a list of changes in each version.

🔗 Links

• Package: pub.flutter-io.cn/packages/logs_spotter
• Repository: github.com/Shek863/logs_spotter
• Issues: github.com/Shek863/logs_spotter/issues
• Example App: example/
• Migration Guide: MIGRATION.md

⭐ Support

If you find this package helpful, please:

• ⭐ Star the repository on GitHub
• 👍 Like the package on pub.flutter-io.cn
• 📢 Share it with other Flutter developers
• 🐛 Report issues or suggest improvements

📄 License

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

---