flutter_logan_pro #

A high-performance, robust log plugin for Flutter based on Meituan Dianping's native Logan library. This version fixes known truncation and decryption issues and provides a more robust and developer-friendly API.

Logs are encrypted and stored locally, and can be easily sent to your server for analysis.

Features #

• High Performance: Asynchronous logging to memory-mapped files.
• Encrypted: Logs are encrypted using AES-128-CBC to protect sensitive data.
• Robust: Pre-initialization log queueing ensures no logs are lost.
• Cross-Platform: Works seamlessly on both Android and iOS.
• Feature Rich: Supports log flushing, log file inspection, and sending logs to a server.
• Error Handling: Returns structured results and handles native exceptions gracefully.

Getting Started #

Add this to your package's pubspec.yaml file:

dependencies:
  flutter_logan_pro: ^1.0.1 # Replace with the latest version

Then, run flutter pub get in your terminal.

Usage #

1. Initialization #

It's crucial to initialize the logger before using it, typically in your main function. This sets up the encryption keys and log directory.

import 'package:flutter_logan_pro/flutter_logan_pro.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await FlutterLoganPro.init(
    secretKey: 'your_16_byte_key', // Must be 16 bytes
    secretIV: 'your_16_byte_iv',   // Must be 16 bytes
    isDebug: !kReleaseMode,       // Enable debug logs from the native library
  );

  runApp(MyApp());
}

2. Logging #

Once initialized, you can log messages from anywhere in your app. Logs that are written before initialization is complete are automatically queued and written once init finishes.

// Simple log
FlutterLoganPro.log('User logged in successfully.');

// Log with a specific type (integer)
FlutterLoganPro.log('Network request failed', type: 2);

3. Sending Logs to a Server #

You can easily send the log file for a specific day to your backend. The send methods return a Future that completes with a LoganSendResult object containing the server's response.

Future<void> uploadTodaysLog() async {
  try {
    String date = (await FlutterLoganPro.getTodaysDate()) ?? '';
    if (date.isEmpty) return;
    
    print('Attempting to send log for date: $date');

    LoganSendResult result = await FlutterLoganPro.send(
      url: 'https://your-server.com/upload',
      appId: 'your-app-id',
      date: date,
      deviceId: 'some-device-id',
    );
    
    print('Send completed.');
    print('Status Code: ${result.statusCode}');
    print('Response Data: ${result.data}');

    if (result.isSuccess()) {
      print('Log uploaded successfully!');
    } else {
      print('Log upload failed.');
    }
  } on StateError catch (e) {
    // Thrown if a send operation is already in progress.
    print('Error: $e');
  } catch (e) {
    print('An unexpected error occurred: $e');
  }
}

You can also send logs with custom headers:

await FlutterLoganPro.sendWithHeaders(
  url: 'https://your-server.com/upload',
  date: '2024-01-01',
  headers: {
    'Authorization': 'Bearer your_token',
    'X-Custom-Header': 'value',
  },
);

4. Other Utility Methods #

The plugin provides several other helpful methods:

// Force any buffered logs to be written to the file.
// This is called automatically before sending.
await FlutterLoganPro.flush();

// Get information about all local log files.
// Returns a map of { 'date': fileSizeInBytes }.
Map<String, int>? files = await FlutterLoganPro.getAllFilesInfo();
print(files);

// Delete all local log files.
await FlutterLoganPro.clearAllLogs();

// Set the maximum number of days to keep log files.
await FlutterLoganPro.setMaxReversedDate(7); // Keep logs for 7 days

Platform-Specific Setup #

Android #

Add the INTERNET permission to your AndroidManifest.xml if it's not already present, which is required for sending logs.

<!-- android/app/src/main/AndroidManifest.xml -->
<uses-permission android:name="android.permission.INTERNET" />

iOS #

No specific platform setup is required. The plugin uses standard APIs.