flutter_remote_logger 0.1.1

A comprehensive remote logging and profiling package for Flutter. Captures sessions, device info, and uploads logs to Firebase or custom backends.

Flutter Remote Logger

A robust Remote Logging and Profiling package for Flutter applications.

flutter_remote_logger captures logs, device metadata, and session information, buffers them locally, and uploads them to a remote target (Firebase or Supabase) entirely in the background logic. It solves the problem of "profiling sessions" where you need to trace user behavior or debug issues on specific devices, even linking anonymous sessions to authenticated users later.

Table of Contents

• Features
• Getting Started
  • Installation
  • Configuration
    • Option A: Firebase
    • Option B: Supabase
• Usage
  • Initialization
  • Logging Events
  • Linking User
  • Force Upload
• Architecture
• Contributing
• License

Features

• Session-based Logging: Every app launch creates a unique Session ID.
• Automatic Metadata: Captures OS, Version, Device Model, and more automatically.
• Local Buffering: Logs are written to secure local storage (.jsonl files) before uploading, preventing data loss on crashes.
• Backend Agnostic: Comes with built-in uploaders for Firebase and Supabase, but you can implement your own.
• User Linking: Link an anonymous device session to a User ID at any point (e.g. after login).

Getting Started

Installation

Add the package to your pubspec.yaml:

dependencies:
  flutter_remote_logger:
    git:
      url: https://github.com/infodreams-software/flutter-remote-logger.git
      # OR, if published:
      # flutter_remote_logger: ^0.1.0

Configuration

You need to choose a backend to store your logs.

Option A: Firebase

1. Dependencies: Add firebase_core, firebase_storage, and cloud_firestore to your app.
2. Initialization: Initialize Firebase in your main.dart.
3. Rules: Ensure your Firestore and Storage have appropriate write rules.
   • Storage path: logs/{deviceId}/{sessionId}.jsonl
   • Firestore path: sessions/{sessionId}

Option B: Supabase

To use Supabase, you need to set up your project with the required tables and storage bucket.

1. Dependencies: Add supabase_flutter to your app.

2. Storage Bucket: Create a public bucket named remote_logs.

3. Database Tables: Run the following SQL in your Supabase SQL Editor:

   -- Table: remote_log_sessions
   create table public.remote_log_sessions (
     session_id uuid not null primary key,
     device_id text not null,
     user_id uuid references auth.users(id), -- Optional foreign key
     start_time timestamptz not null,
     end_time timestamptz,
     app_version text,
     os_version text,
     device_model text,
     custom_data jsonb,
     log_file_url text,
     uploaded_at timestamptz default now()
   );
   
   create index idx_remote_log_sessions_device on public.remote_log_sessions(device_id);
   create index idx_remote_log_sessions_user on public.remote_log_sessions(user_id);
   
   -- Table: remote_log_device_links
   create table public.remote_log_device_links (
     id bigint generated by default as identity primary key,
     device_id text not null,
     user_id uuid not null references auth.users(id),
     linked_at timestamptz default now()
   );
   
   create index idx_remote_log_device_links_user on public.remote_log_device_links(user_id);
   

4. RLS Policies: Don't forget to enable RLS and add policies to allow insert for authenticated/anonymous users as needed.

Usage

Initialization

Initialize RemoteLogger early in your app lifecycle. You must inject the appropriate LogUploader.

Example: Using Firebase

import 'package:flutter_remote_logger/flutter_remote_logger.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp();

  // Initialize with FirebaseUploader (default is null/noop if not provided?)
  // Actually, you typically just let it rely on default imports or pass explicitly:
  await RemoteLogger().initialize(
    uploader: FirebaseLogUploader(),
    // Optional: Upload logs every 5 minutes automatically
    autoUploadFrequency: const Duration(minutes: 5),
  );

  runApp(MyApp());
}

Example: Using Supabase

import 'package:flutter_remote_logger/flutter_remote_logger.dart';
import 'package:supabase_flutter/supabase_flutter.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  await Supabase.initialize(
    url: 'YOUR_SUPABASE_URL',
    anonKey: 'YOUR_SUPABASE_ANON_KEY',
  );

  await RemoteLogger().initialize(
    uploader: SupabaseLogUploader(
      supabaseClient: Supabase.instance.client,
      // Optional: configuration
      // bucketName: 'my_logs',
    ),
  );

  runApp(MyApp());
}

Logging Events

Log anywhere in your app. The API is similar to standard logging.

// Simple info log
RemoteLogger().log('App loaded successfully');

// Log with level and custom tag
RemoteLogger().log('Database connected', level: 'DEBUG', tag: 'DB');

// Log structured data (Payload)
try {
  // ... risky code
} catch (e) {
  RemoteLogger().log(
    'Initialization failed', 
    level: 'ERROR', 
    payload: {
      'error': e.toString(),
      'retryCount': 3,
    }
  );
}

Linking User

When a user authenticates, linking their User ID to the session allows you to find their logs later by User ID instead of just Device ID.

void onUserLogin(String userId) {
  RemoteLogger().identifyUser(userId);
}

Force Upload

Logs are locally buffered in files. You can trigger a manual upload of the current session file at any time (e.g. on important errors or app pause).

await RemoteLogger().uploadCurrentSession();

Architecture

The package is designed to be modular.

• RemoteLogger: The singleton facade.
• LogStorage: Controls where logs are temporarily saved (Default: FileLogStorage).
• LogUploader: Controls where logs go (implementations: FirebaseLogUploader, SupabaseLogUploader).

Contributing

Contributions are welcome! Please submit a PR or open an issue.

License

MIT License. See LICENSE file.