📦 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.

offline_logger 0.0.1 offline_logger: ^0.0.1 copied to clipboard

Metadata