AutoLogCapture

Automatic log interception library for Android and React Native applications. Captures logs from multiple sources and syncs them to your logging platform without requiring custom logging code.

Repository: https://github.com/eben-flow/android-remote-logger

Features

• Automatic Log Capture: Intercepts Android logcat and JavaScript console logs
• Direct Log Capture: Use AutoLog API to bypass logcat's 4096 character truncation limit
• Crash & ANR Detection: Automatically reports crashes and Application Not Responding events
• Pluggable Sync Providers: Send logs to OpenObserve, Elasticsearch, Splunk, custom HTTP endpoints, or local files
• React Native Support: Captures JavaScript console logs via bridge module
• Tag Filtering: Include/exclude specific log tags with whitelist/blacklist support
• Batch Upload: Efficient batching and GZIP compression for network efficiency
• File-based Storage: Persistent storage with automatic cleanup after successful sync

Installation

For React Native Projects (Recommended)

Step 1: Install the Package

npm install react-native-logcapture
# or
yarn add react-native-logcapture

Step 2: Android Native Setup

2.1. Initialize in MainApplication.java:

import com.autologcapture.AutoLogCapture;
import com.autologcapture.providers.OpenObserveProvider;
import com.autologcapture.models.LogLevel;
import com.autologcapture.format.JsonLogFormatter;

public class MainApplication extends Application implements ReactApplication {

    @Override
    public void onCreate() {
        super.onCreate();

        JsonLogFormatter formatter = new JsonLogFormatter();

        // Configure OpenObserve provider
        OpenObserveProvider provider = new OpenObserveProvider(
            "https://api.openobserve.ai",      // Your OpenObserve URL
            "your-username",                    // Your username
            "your-password",                    // Your password
            "default",                          // Organization name
            "android-logs",                   // Stream name
            formatter,                        // Json format
            true                              // compression enabled
        );

        // Initialize AutoLogCapture (only initializes once)
        AutoLogCapture.setSyncProvider(provider);
        AutoLogCapture.init(this);

        // Optional: Configure behavior
        AutoLogCapture.setSyncInterval(30);              // Sync every 30 seconds
        AutoLogCapture.setLogLevel(LogLevel.INFO);       // Only INFO and above
        AutoLogCapture.setStorageLimits(
            10 * 1024 * 1024,    // 10 MB per file
            100 * 1024 * 1024    // 100 MB total
        );

        // Delete logs older than 7 days
        AutoLogCapture.deleteLogsOlderThan(7);
    }
}

Step 3: Enable JavaScript Console Capture (Two-Gate System)

JavaScript console logging requires both gates to be enabled:

3.1. JavaScript Gate - Add to your index.js (at the very top):

import { initializeConsoleCapture } from 'react-native-logcapture';

// Initialize console capture - must be called before any console.log statements
initializeConsoleCapture();

3.2. Native Gate - Enable in MainApplication.java (after init()):

Console logging requires enabling both the JavaScript interceptor AND the native flag:

AutoLogCapture.init(this);
AutoLogCapture.setEnableConsoleLogging(true);  // Enable native gate

Both must be enabled for console logs to be captured.

Advanced Usage

Direct Logging API (No Truncation)

AutoLogCapture provides two ways to capture logs:

1. Automatic logcat capture - Intercepts existing Log.d/i/w/e calls (limited to 4096 chars)
2. Direct capture via AutoLog - Bypasses logcat, captures full untruncated logs

Using AutoLog for Untruncated Android Logs

Replace android.util.Log with AutoLog to capture full messages without the 4096 character limit:

import com.autologcapture.AutoLog;

// Before (truncated at 4096 chars):
Log.d("MyTag", veryLongMessage);

// After (no truncation):
AutoLog.d("MyTag", veryLongMessage);

Include-Only Mode (Whitelist)

Only capture logs with specific tags:

AutoLogCapture.setIncludeOnlyMode(true);
AutoLogCapture.addIncludeTag("JSConsole");     // Capture JS console logs
AutoLogCapture.addIncludeTag("MyApp");         // Capture your app logs
AutoLogCapture.addIncludeTag("NetworkAPI");    // Capture network logs

// Or set multiple at once
AutoLogCapture.setIncludeTags("JSConsole", "MyApp", "NetworkAPI");

// Remove tags from include list
AutoLogCapture.removeIncludeTag("NetworkAPI");

// Clear all included tags
AutoLogCapture.clearIncludeTags();

Block Mode (Blacklist)

Block specific tags from being captured:

// Block noisy Android system tags
AutoLogCapture.blockTag("Choreographer");
AutoLogCapture.blockTag("OpenGLRenderer");
AutoLogCapture.blockTag("GC");

// Block multiple at once
AutoLogCapture.blockTags("Choreographer", "OpenGLRenderer", "GC");

// Supports prefix matching - block all tags starting with "BF/"
AutoLogCapture.blockTag("BF/");

// Remove from blocked list
AutoLogCapture.removeBlockedTag("GC");

Note: Blocked tags are filtered in both default mode and include-only mode.

Configuration Options

Sync Settings

// Sync interval (10-3600 seconds, default: 20 seconds)
AutoLogCapture.setSyncInterval(60); // Every minute

// Manual sync
AutoLogCapture.forceSync();

Retry Strategy

AutoLogCapture uses a retry mechanism with cumulative exponential backoff:

Initial Retries (Failures 1-3):

• Retry at the configured sync interval (e.g., 20 seconds)
• Quick recovery for transient network issues

Network Check (After 3rd failure):

• Checks if network is available
• If no network: Pauses sync and starts network monitor (event-driven recovery)
• If network available: Switches to cumulative exponential backoff

Cumulative Backoff (Failures 4+):

For a 20-second sync interval:

• 4th failure: 20 + 10 = 30s delay
• 5th failure: 30 + 20 = 50s delay
• 6th failure: 50 + 30 = 80s delay
• 7th failure: 80 + 60 = 140s delay
• 8th failure: 140 + 120 = 260s delay
• 9th+ failure: Resets to 20 + 10 = 30s and loops through sequence again

On Success:

• Resets to normal sync interval immediately
• Clears all failure tracking

Storage Settings

1. Default Storage - 5MB per file, 50MB total

2. Minimum storage required - 10KB per file, 5MB total

AutoLogCapture.setStorageLimits(
    10 * 1024 * 1024,   // 10 MB per file
    100 * 1024 * 1024   // 100 MB total
);

// Configure sync batch limits to prevent oversized payloads (default: 500 entries per batch, 5MB max payload)
AutoLogCapture.setSyncBatchLimits(
    1000,               // Max 1000 entries per batch
    10 * 1024 * 1024    // Max 10 MB per sync payload
);

// Get current batch limits
long[] limits = AutoLogCapture.getSyncBatchLimits();
int maxBatchSize = (int) limits[0];      // 1000 entries
long maxPayloadSize = limits[1];          // 10485760 bytes (10MB)

File Cleanup:

• Successfully synced files are automatically deleted after upload
• Emergency cleanup triggers when storage exceeds 2x the limit
• File rotation happens when individual files exceed max size
• Old files cleaned up on app startup

Log Levels

// Minimum log level (default: DEBUG)
AutoLogCapture.setLogLevel(LogLevel.WARN); // Only WARN, ERROR, FATAL

Crash & ANR Settings

// Enable/disable features (default: both enabled)
AutoLogCapture.enableCrashReporting(true);
AutoLogCapture.enableANRDetection(true);

// Add crash metadata
AutoLogCapture.addCrashMetadata("userId", "12345");
AutoLogCapture.addCrashMetadata("environment", "production");

Sync Providers

Generic HTTP

Send logs to any HTTP endpoint with custom headers and formatters.

import com.autologcapture.providers.GenericHttpProvider;

GenericHttpProvider provider = new GenericHttpProvider.Builder()
    .endpoint("https://api.example.com/logs")
    .header("Authorization", "Bearer YOUR_TOKEN")
    .header("X-App-Version", "1.0.0")
    .header("X-Device-Id", "device-123")
    .compression(true)  // Enable GZIP compression
    .build();

AutoLogCapture.setSyncProvider(provider);

Local File

Store logs to local files for offline scenarios.

import com.autologcapture.providers.FileProvider;

FileProvider provider = new FileProvider(context, "my-app-logs");
AutoLogCapture.setSyncProvider(provider);

// Access log files later
File[] logFiles = provider.getLogFiles();
File[] crashFiles = provider.getCrashFiles();

How It Works

Sync & Upload Flow

1. Log Capture → Logs captured from logcat, crashes, ANRs, and JS console
2. Tag Filtering → ProcessFilter applies include/exclude rules
3. File Storage → Each log saved as individual JSON file (5MB max per file, 50MB total)
4. Scheduled Sync → AutoSyncScheduler runs every 20 seconds (configurable)
5. Retry Logic → Retry with cumulative exponential backoff on failure
6. Incremental Upload → Only unsynced logs uploaded (SyncState tracking)
7. Auto Cleanup → Successfully uploaded files deleted automatically

File Management

Storage Limits:

• Default: 5MB per file, 50MB total
• Configurable via setStorageLimits()
• File rotation when limits exceeded
• Emergency cleanup at 2x limit threshold

Cleanup Schedule:

• On app startup: Clean old files
• After successful sync: Delete uploaded files immediately
• On storage limit change: Immediate cleanup if new limit is lower
• User-triggered: deleteLogsOlderThan(Date) for retention policies

Crash File Handling:

• Stored separately in /files/logs/crashes/
• Kept 7 extra days beyond regular log retention
• High-priority immediate upload
• Never auto-deleted before successful sync

Configuration

Enabling/Disabling Log Capture

By default, AutoLogCapture automatically starts capturing:

• Logcat output (disabled by default)
• Crashes and ANRs (disabled by default)
• JavaScript console logs (requires both JavaScript AND native gates enabled)

You can control what gets captured:

Enable Logcat Capture (Optional)

Logcat is disabled by default to save resources. Enable it if you need to capture third-party library logs:

// In MainApplication.java - before init()
AutoLogCapture.setSyncProvider(provider);
AutoLogCapture.init(this);
AutoLogCapture.setEnableLogcatLogging(true);

When to enable logcat:

• You need to capture third-party library logs (they use android.util.Log)
• You have existing Log.d/i/w/e calls and don't want to change them
• You want automatic capture without code changes

When to keep it disabled (default):

• You're only using AutoLog API for direct logging
• You are already using console logging
• You want to reduce resource usage (saves 2 background threads)
• Logcat is blocked on your target devices (Knox, restricted ROMs)

Note: Enabling both console and logcat logging might lead to duplicate logs if tag filtering isn't applied

Architecture

┌─────────────────────────────────────────────────────────────┐
│                     AutoLogCapture API                       │
│                  (Public static methods)                     │
└─────────────────┬───────────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────────────────────────────┐
│                    LoggerManager                             │
│  (Coordinates capture, storage, sync + implements listeners)│
└──────┬──────────────────┬──────────────────┬────────────────┘
       │                  │                  │
       ▼                  ▼                  ▼
┌─────────────┐  ┌──────────────┐  ┌──────────────┐
│ LogcatReader│  │ CrashHandler │  │  ANRWatchdog │
│             │  │              │  │              │
│ (logcat -v  │  │ (Uncaught    │  │ (Main thread │
│  time)      │  │  exceptions) │  │  blocking)   │
└─────┬───────┘  └──────┬───────┘  └──────┬───────┘
      │                 │                  │
      └─────────┬───────┴──────────────────┘
                ▼
┌─────────────────────────────────────────────────────────────┐
│                   ProcessFilter                              │
│   (Tag filtering: include/exclude/block lists)               │
└─────────────────────────┬───────────────────────────────────┘
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                     FileStorage                              │
│  (Direct file storage with configurable limits)              │
│  Default: 5MB/file, 50MB total                               │
└───────┬─────────────────────────────────────────────────────┘
        │
        ├─→ SyncState (tracks synced/pending entries)
        │
        ▼
┌─────────────────────────────────────────────────────────────┐
│                   AutoSyncScheduler                          │
│  (20s sync + cumulative exponential backoff + network-aware) │
│  NetworkStateMonitor (lazy activation on network failure)    │
└─────────────────────────┬───────────────────────────────────┘
                          │
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                  LogSyncProvider                             │
│   (OpenObserve / GenericHTTP / FileProvider / Custom)        │
└─────────────────────────────────────────────────────────────┘

Requirements

• Android SDK 21+ (Android 5.0 Lollipop)
• React Native 0.60+ (for React Native integration)

Support

• GitHub Issues: https://github.com/eben-flow/android-remote-logger/issues
• Documentation: See TAG_FILTERING_GUIDE.md