flutter_logan_pro 1.0.3

A high-performance, robust log plugin for Flutter based on Meituan Logan. Fixed truncation and decryption issues.

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',
  },
);

Platform note: Custom headers are only honored on Android. iOS's native Logan upload API does not accept request headers, so on iOS they are ignored and the log is uploaded without them. Similarly, buildVersion/appVersion on send() are forwarded only on Android.

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.