📦 Offline Logger SDK – Enterprise Documentation

🚀 Overview

Offline Logger is a production-grade, offline-first observability SDK for Flutter applications.

It enables:

  • Reliable logging in low/no internet environments
  • Crash tracking and debugging
  • Automatic batching and syncing
  • Scalable observability for large deployments

🧱 Architecture

App Layer
   ↓
OfflineLogger SDK
   ↓
Hive Storage (Local DB)
   ↓
Sync Engine (Retry + Batch)
   ↓
Backend API

⚙️ Initialization

init(LoggerConfig config)

Purpose

Initializes entire SDK system.

Responsibilities

  • Initializes Hive
  • Creates SyncService
  • Generates sessionId
  • Fetches device info
  • Starts heartbeat
  • Sets lifecycle + connectivity listeners
  • Flushes pre-init logs

Usage

await OfflineLogger.init(
  LoggerConfig(
    apiEndpoint: "https://api.yourserver.com/logs",
    enableDebugLogs: true,
  ),
);

🧠 Logging APIs

log()

General logging

OfflineLogger.log("User clicked button");

error()

Recoverable errors

OfflineLogger.error("API failed");

crash()

Critical crash logging

OfflineLogger.crash(error, stack);

🏷️ Tagged Logging

logWithTag()

OfflineLogger.logWithTag("VIDEO", "Playback started");

errorWithTag()

OfflineLogger.errorWithTag("API", "Login failed");

🧾 Metadata

setGlobalMetadata()

Adds metadata to all logs

OfflineLogger.setGlobalMetadata({
  "userId": "123",
  "schoolId": "UP_1023",
});

restartSession()

Creates new session

OfflineLogger.restartSession();

🔄 Sync System

sync()

Triggers log upload

Features

  • Batch processing
  • Retry with backoff
  • Timeout protection
  • Sync locking

safeSync()

Safe wrapper

await OfflineLogger.safeSync();

flush()

Force upload logs

await OfflineLogger.flush();

📤 Data Access

exportLogs()

final logs = await OfflineLogger.exportLogs();

🧹 Cleanup

dispose()

await OfflineLogger.dispose();

📱 Crash Handling

runAppWithLogger()

Wrap app

OfflineLogger.runAppWithLogger(() {
  runApp(MyApp());
});

🔁 Internal Mechanisms

Pre-init Queue

  • Stores logs before init
  • Max size: 100
  • Auto flushed

Sync Engine

  • Batching
  • Retry
  • Timeout (15s)

Connectivity

  • Debounced sync trigger

Heartbeat

  • Runs every 5 min

📦 Log Structure

{
  "id": "uuid",
  "type": "info",
  "message": "...",
  "priority": "low",
  "metadata": {},
  "timestamp": "ISO",
  "isSynced": false
}

📊 Captured Data

Automatic

  • Flutter errors
  • Unhandled exceptions
  • Lifecycle events
  • Connectivity changes

Manual

  • User actions
  • API failures
  • Business logic

⚠️ Limitations

  • No native crash capture
  • No ANR detection
  • No performance monitoring

🧠 Best Practices

Do

  • Log meaningful events
  • Use metadata
  • Use tagging

Avoid

  • Sensitive data
  • Large payloads
  • Over-logging

🚀 Production Readiness

✔ Offline-first
✔ Retry + batching
✔ Scalable
✔ Memory-safe
✔ No log loss

📌 Summary

Offline Logger provides a complete observability layer for Flutter apps, optimized for low-connectivity environments and large-scale deployments.

Libraries

offline_logger