flutter_logs

A file based advanced logging framework for Flutter Apps (Android & iOS).

Overview

Flutter Logs provides quick & simple file based logging solution. All logs are saved to files in storage path provided. A new log file is created every hour on a new log event. These logs can be filtered and sorted easily. Logs can easily be exported as zip file base on filter type. PLogs also provide functionality to arrange data logs into a predefined directory structure. Custom logs can be used for a specific events based logging within the app. Logs can be saved as encrypted for security purposes.

Flutter logs can work with Logstash by writing JSON delimited logs to log files. The format is based on ELK schema. You can also send logs in real-time to server using MQTT. MQTT configuration can be applied on Logstash to receive & view logs on kibana dashboard.

Options 1	Options 2

Features (Android)

Logs events in files created separately every hour (24 hours event based)
Files can be compressed and exported for time and day filters
Clear Logs easily
Save & Export Logs to app's directory as zip file
Custom Log formatting options
CSV support
Custom timestamps support
Custom file data logging support.
Encryption support added
Multiple directory structures
Print logs as String
Export all or single types of logs
ELK Stack Supported See more about it here.
MQTT Support (SSL)
Backpressure support for high-volume logging scenarios
Redaction & Masking for sensitive data (PII protection)
Search & Filter logs by keywords

Features (iOS)

Note: Work is in progress. More features will be added soon.

Logs events in files
Files can be compressed and exported
Clear Logs easily
Save & Export Logs to app's directory as zip file
Print logs as String

Install

In your pubspec.yaml

dependencies:
    flutter_logs: [Latest]

import 'package:flutter_logs/flutter_logs.dart';

Setting Up

Initialization

Call FlutterLogs.initLogs before runApp. Three parameters are required; everything else has a default.

import 'package:flutter_logs/flutter_logs.dart';

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

  await FlutterLogs.initLogs(
    // --- required ---
    directoryStructure: DirectoryStructure.FOR_DATE,
    timeStampFormat: TimeStampFormat.TIME_FORMAT_READABLE,
    logFileExtension: LogFileExtension.LOG,

    // --- commonly set ---
    logLevelsEnabled: [
      LogLevel.INFO,
      LogLevel.WARNING,
      LogLevel.ERROR,
      LogLevel.SEVERE,
    ],
    logTypesEnabled: ["device", "network", "errors"],
    logsWriteDirectoryName: "MyLogs",
    logsExportDirectoryName: "MyLogs/Exported",
    logsRetentionPeriodInDays: 14,
    isDebuggable: true,
  );

  runApp(MyApp());
}

`initLogs` — Full Parameter Reference

Parameter	Type	Default	Description
`directoryStructure`	`DirectoryStructure`	required	How log files are arranged on disk. See values below.
`timeStampFormat`	`TimeStampFormat`	required	Timestamp format appended to each log entry. See values below.
`logFileExtension`	`LogFileExtension`	required	File extension for log files. See values below.
`logLevelsEnabled`	`List<LogLevel>?`	`null` (all)	Which log levels are written to file. Omit to enable all levels.
`logTypesEnabled`	`List<String>?`	`null`	Names of custom log-type files (used with `logToFile`).
`logsRetentionPeriodInDays`	`int`	`14`	Log files older than this are deleted automatically.
`zipsRetentionPeriodInDays`	`int`	`3`	Exported zip files older than this are deleted automatically.
`autoDeleteZipOnExport`	`bool`	`false`	Delete the zip file from the export directory after a successful export.
`autoClearLogs`	`bool`	`true`	Automatically clear log files when retention period expires.
`autoExportErrors`	`bool`	`true`	Automatically export `ERROR`/`SEVERE` logs when they occur.
`encryptionEnabled`	`bool`	`false`	Encrypt log files on disk. Requires `encryptionKey`.
`encryptionKey`	`String`	`""`	AES encryption key. Only used when `encryptionEnabled` is `true`.
`logSystemCrashes`	`bool`	`true`	Capture uncaught exceptions and log them automatically.
`isDebuggable`	`bool`	`true`	Print internal plugin debug messages to the console.
`debugFileOperations`	`bool`	`true`	Log file read/write operations to the console for tracing.
`attachTimeStamp`	`bool`	`true`	Prepend a timestamp to each log entry.
`attachNoOfFiles`	`bool`	`true`	Append the current file count to each log entry.
`zipFilesOnly`	`bool`	`false`	Export logs as a zip even when a single file would suffice.
`logsWriteDirectoryName`	`String`	`""`	Subdirectory name inside app storage where logs are written.
`logsExportZipFileName`	`String`	`""`	Custom name for the exported zip file (without extension).
`logsExportDirectoryName`	`String`	`""`	Subdirectory inside app storage where exported zips are placed.
`singleLogFileSize`	`int`	`2`	Maximum size of a single log file in MB before a new one is created.
`enabled`	`bool`	`true`	Master switch — set to `false` to disable all logging without changing config.
`forceWriteLogs`	`bool`	`true`	Write logs immediately even when the internal buffer is not full.
`enableLogsWriteToFile`	`bool`	`true`	Write log entries to files. Disable to log to console only.
`formatType`	`FormatType`	`FORMAT_CURLY`	Structure of each log entry. See values below.
`customFormatOpen`	`String`	`" "`	Opening delimiter used when `formatType` is `FORMAT_CUSTOM`.
`customFormatClose`	`String`	`" "`	Closing delimiter used when `formatType` is `FORMAT_CUSTOM`.
`logFilesLimit`	`int`	`100`	Maximum number of log files kept on disk before the oldest are removed.
`nameForEventDirectory`	`String`	`""`	Directory name for event logs. Used when `directoryStructure` is `FOR_EVENT`.
`autoExportLogTypes`	`List<String>?`	`null`	Log-type names that are exported automatically on a timer.
`autoExportLogTypesPeriod`	`int`	`0`	Interval in minutes between automatic exports. `0` disables the timer.
`csvDelimiter`	`String`	`""`	Column separator used when `formatType` is `FORMAT_CSV`.
`exportFormatted`	`bool`	`true`	Apply formatting rules when exporting (pretty-print).
`exportFileNamePreFix`	`String`	`""`	String prepended to the exported zip file name.
`exportFileNamePostFix`	`String`	`""`	String appended to the exported zip file name.
`backpressureConfig`	`BackpressureConfig?`	`null`	Queue and per-level quota settings for high-volume logging. See Backpressure below.
`redactionConfig`	`RedactionConfig?`	`null`	PII masking rules applied before writing each log entry. See Redaction below.

Enum Values

DirectoryStructure

Value	Description
`FOR_DATE`	One directory per date, one file per hour inside it.
`FOR_EVENT`	All logs grouped into a single named event directory (`nameForEventDirectory`).
`SINGLE_FILE_FOR_DAY`	One log file per day.

TimeStampFormat

Value	Example output
`DATE_FORMAT_1`	`2024-01-15`
`DATE_FORMAT_2`	`15-01-2024`
`TIME_FORMAT_FULL_JOINED`	`150120241030`
`TIME_FORMAT_FULL_1`	`15-01-2024 10:30:00`
`TIME_FORMAT_FULL_2`	`15/01/2024 10:30:00`
`TIME_FORMAT_24_FULL`	`2024-01-15 10:30:00`
`TIME_FORMAT_READABLE`	`15 January 2024 10:30 AM`
`TIME_FORMAT_READABLE_2`	`Jan 15, 2024 10:30 AM`
`TIME_FORMAT_SIMPLE`	`10:30:00`

LogFileExtension

Value	Extension
`LOG`	`.log`
`TXT`	`.txt`
`CSV`	`.csv`
`NONE`	(no extension)

LogLevel

Value	Use for
`INFO`	General informational events
`WARNING`	Potentially harmful situations
`ERROR`	Error events that allow the app to continue
`SEVERE`	Critical failures

FormatType

Value	Entry format
`FORMAT_CURLY`	`{tag} {message} {timestamp}`
`FORMAT_SQUARE`	`[tag] [message] [timestamp]`
`FORMAT_CSV`	Comma-separated (or `csvDelimiter`) columns
`FORMAT_CUSTOM`	Uses `customFormatOpen` / `customFormatClose` as delimiters

ExportType (used in export calls, not initLogs)

Value	Exports logs from
`TODAY`	The current day
`LAST_HOUR`	The last 60 minutes
`LAST_24_HOURS`	The last 24 hours
`WEEKS`	The last 7 days
`ALL`	All retained log files

How to log data?

You have 2 choices for logging:

Hourly Logs

Hourly logs are automatically generated once this line is called. These logs are sorted and named according to current time (24h format) on device e.g. 0110202013.log

FlutterLogs.logThis(
        tag: 'MyApp',
        subTag: 'logData',
        logMessage:
            'This is a log message: ${DateTime.now().millisecondsSinceEpoch}',
        level: LogLevel.INFO);

Or simply call this:

    FlutterLogs.logInfo("TAG", "subTag", "My Log Message");
    
    FlutterLogs.logWarn("TAG", "subTag", "My Log Message");
    
    FlutterLogs.logError("TAG", "subTag", "My Log Message");
    
    FlutterLogs.logErrorTrace("TAG", "subTag", "My Log Message", Error());

This will create a new file in storage directory according to time on device. For a single date, all logs will be present in a single directory.

Custom File Logs

If you want to log data into a specific file for some events, you can do this in 2 steps:

These logs will be kept in a seperate file.

Step 1:

[IMPORTANT] Define log file name in logs configuration, logger needs the name to find the file on storage, otherwise no data will be logged.

Here 3 files of logs are defined, logger will use these file name as keys to write data in them.

    await FlutterLogs.initLogs(
        logTypesEnabled: ["Locations","Jobs","API"]);

Step 2:

Log data to file. You can choose to either append to file or overwrite to complete file.

    FlutterLogs.logToFile(
        logFileName: "Locations",
        overwrite: false,
        logMessage:
            "{0.0,0.0}");

Where are my logs stored?

Your logs can be found in the path of your app's directory in storage:

Android:

--> Android/data/[YOUR_APP_PACKAGE]/files/[YOUR_LOGS_FOLDER_NAME]/Logs/

iOS:

--> [YOUR_APP_CONTAINER]/AppData/Library/Application Support/Logs/

Export/Print Logs

You can export logs to output path sepcified in logs configuration:

    await FlutterLogs.initLogs(
        logsExportDirectoryName: "MyLogs/Exported");

To export logs call this:

    FlutterLogs.exportLogs(
        exportType: ExportType.ALL);

    FlutterLogs.printLogs(
        exportType: ExportType.ALL);

To export custom file logs:

 FlutterLogs.exportFileLogForName(
        logFileName: "Locations");

 FlutterLogs.printFileLogForName(
        logFileName: "Locations");

Listen to export/print results:

    import 'dart:async';
    import 'dart:io';
    import 'package:flutter_logs/flutter_logs.dart';
    import 'package:path_provider/path_provider.dart';

    FlutterLogs.channel.setMethodCallHandler((call) async {
        if (call.method == 'logsExported') {
          var zipName = "${call.arguments.toString()}";

            Directory externalDirectory;

            if (Platform.isIOS) {
              externalDirectory = await getApplicationDocumentsDirectory();
            } else {
              externalDirectory = await getExternalStorageDirectory();
            }

            FlutterLogs.logInfo(TAG, "found", 'External Storage:$externalDirectory');

          File file = File("${externalDirectory.path}/$zipName");

          FlutterLogs.logInfo(
              TAG, "path", 'Path: \n${file.path.toString()}');

          if (file.existsSync()) {
            FlutterLogs.logInfo(
                TAG, "existsSync", 'Logs found and ready to export!');
          } else {
            FlutterLogs.logError(
                TAG, "existsSync", "File not found in storage.");
          }
          
        } else if (call.method == 'logsPrinted') {
          //TODO Get results of logs print here
        }
      });

Exports logs manually

Include dependency:

         flutter_archive: ^6.0.3

       Directory? externalDirectory;
      
       if (Platform.isIOS) {
           externalDirectory = await getApplicationDocumentsDirectory();
       } else {
           externalDirectory = await getExternalStorageDirectory();
       }

      File file = File("${externalDirectory!.path}/$_logsDirectory");
      
      final zipFile = File("${externalDirectory.path}/logs.zip");
      try {
           await ZipFile.createFromDirectory(
           sourceDir: Directory(file.path),
           zipFile: zipFile,
           includeBaseDirectory: true);
      } catch (e) {
           print(e);
      }

      logInfo(_tag, "uploadFile", 'Storage:${file.path}, Zip: ${zipFile.path}');
}

Clear Logs

 FlutterLogs.clearLogs();

Errors/Exception Logs

Printing exception logs:

      try {
          var i = 100 ~/ 0;
          print("$i");
      } catch (e) {
          FlutterLogs.logThis(
              tag: 'MyApp',
              subTag: 'Caught an exception.',
              logMessage: 'Caught an exception!',
              exception: e,
              level: LogLevel.ERROR);
      }

Printing error logs:

      try {
          var i = null;
          print(i * 10);
      } catch (e) {
          FlutterLogs.logThis(
              tag: 'MyApp',
              subTag: 'Caught an error.',
              logMessage: 'Caught an exception!',
              error: e,
              level: LogLevel.ERROR);
      }

Backpressure Support

Backpressure helps manage high-volume logging scenarios by limiting queue size and setting quotas per log level to prevent memory issues and ensure critical logs are prioritized.

    await FlutterLogs.initLogs(
        // ... other configurations ...
        backpressureConfig: BackpressureConfig(
          queueCapacity: 500,        // Max logs in queue before dropping
          warnQueueCapacity: 400,    // Warn when queue reaches this size
          perLevelQuotas: {
            LogLevel.INFO: 100,      // Max 100 INFO logs per window
            LogLevel.WARNING: 50,    // Max 50 WARNING logs per window
            LogLevel.ERROR: 200,     // Prioritize error logs
            LogLevel.SEVERE: 200,    // Prioritize severe logs
          },
          quotaWindowMillis: 60000,  // 1 minute window for quotas
        ),
    );

Redaction & Masking (PII Protection)

Automatically mask sensitive data like emails, phone numbers, credit cards, and custom patterns in your logs for privacy and security compliance.

Built-in Patterns

    await FlutterLogs.initLogs(
        // ... other configurations ...
        redactionConfig: RedactionConfig(
          enableBuiltInPatterns: {
            BuiltInPattern.EMAIL,        // Masks email addresses
            BuiltInPattern.PHONE_NUMBER, // Masks phone numbers
            BuiltInPattern.CREDIT_CARD,  // Masks credit card numbers
            BuiltInPattern.JWT_TOKEN,    // Masks JWT tokens
            BuiltInPattern.IP_ADDRESS,   // Masks IP addresses
          },
          defaultMaskType: MaskType.FULL_MASK,
        ),
    );

Custom Redaction Rules

You can define custom rules with regex patterns:

    await FlutterLogs.initLogs(
        // ... other configurations ...
        redactionConfig: RedactionConfig(
          enableBuiltInPatterns: {BuiltInPattern.EMAIL},
          customRules: [
            // Mask SSN patterns (XXX-XX-XXXX)
            RedactionRule(
              name: 'SSN',
              patternString: r'\b\d{3}-\d{2}-\d{4}\b',
              maskType: MaskType.FULL_MASK,
            ),
            // Partially mask API keys (show first 4 chars)
            RedactionRule(
              name: 'API_KEY',
              patternString: r'api_key[=:]\s*([A-Za-z0-9]{20,})',
              maskType: MaskType.PARTIAL,
            ),
            // Hash user IDs for tracking without exposing actual IDs
            RedactionRule(
              name: 'USER_ID',
              patternString: r'user_id[=:]\s*(\d+)',
              maskType: MaskType.HASH,
            ),
            // Custom replacement text
            RedactionRule(
              name: 'PASSWORD',
              patternString: r'password[=:]\s*\S+',
              maskType: MaskType.FULL_MASK,
              replacement: 'password=[REDACTED]',
            ),
          ],
          defaultMaskType: MaskType.FULL_MASK,
        ),
    );

Mask Types

MaskType	Description	Example
`FULL_MASK`	Completely masks the value	`john@email.com` → `[REDACTED]`
`PARTIAL`	Shows partial value	`sk_live_abc123xyz` → `sk_l****`
`HASH`	Replaces with hash	`user_id=12345` → `user_id=[HASH:a1b2c3]`

Search & Filter Logs

Search through all log files for specific keywords and export or print only matching lines.

Export Filtered Logs

    FlutterLogs.exportFilteredLogs(
      keywords: ['ERROR', 'login', 'failed'],
      filterType: FilterType.OR,    // Match ANY keyword (use AND to match ALL)
      exportType: ExportType.ALL,
      ignoreCase: true,
    );

Print Filtered Logs

    FlutterLogs.printFilteredLogs(
      keywords: ['network', 'timeout'],
      filterType: FilterType.AND,   // Match ALL keywords
      exportType: ExportType.TODAY,
      ignoreCase: true,
    );

Filter Types

FilterType	Description
`FilterType.OR`	Match lines containing ANY of the keywords
`FilterType.AND`	Match lines containing ALL of the keywords

ELK Elastic Stack Schema Support

Send additional Meta info for better filtering at LogStash dashboard. With this setting, logs will be logged as JSON-delemited.

    await FlutterLogs.setMetaInfo(
      appId: "flutter_logs_example",
      appName: "Flutter Logs Demo",
      appVersion: "1.0",
      language: "en-US",
      deviceId: "00012",
      environmentId: "7865",
      environmentName: "dev",
      organizationId: "5767",
      userId: "883023-2832-2323",
      userName: "umair13adil",
      userEmail: "m.umair.adil@gmail.com",
      deviceSerial: "YJBKKSNKDNK676",
      deviceBrand: "LG",
      deviceName: "LG-Y08",
      deviceManufacturer: "LG",
      deviceModel: "989892BBN",
      deviceSdkInt: "26",
      latitude: "0.0",
      longitude: "0.0",
      labels: {"env": "dev"},
    );

Output of logs will be like this:

{
  "user": {
    "user.email": "m.umair.adil@gmail.com",
    "user.full_name": "umair",
    "user.id": "17282738",
    "user.hash": "1",
    "user.name": "Umair"
  },
  "message": "{OkHttpClient}  {X-XSS-Protection: 1; mode=block} [30 June 2020 04:15:16 PM]",
  "@version": "1",
  "log.logger": "PLogger",
  "host": {
    "host.type": "Android",
    "host.name": "LG",
    "host.architecture": "LG 23",
    "host.hostname": "8000",
    "host.id": "LG",
    "host.ip": "0.0.0.0",
    "host.mac": ""
  },
  "labels": "{}",
  "app": {
    "app.language": "en-US",
    "app.id": "com.example.develop",
    "app.name": "Flutter Dev",
    "app.version": "0.0.108"
  },
  "process.thread.name": "DATA_LOG",
  "organization": {
    "organization.name": "debug",
    "organization.id": "BlackBox"
  },
  "geo": {
    "geo.location": "{ \"lon\": 0.0, \"lat\": 0.0 }"
  },
  "service.name": "Network",
  "@timestamp": "2020-06-30T16:27:36.894Z",
  "topic": "com.flutter.elk.logs",
  "log.level": "INFO"
}

Enable MQTT Feature

Note: PLogger currently supports SSL connection for MQTT.

Step 1:

Add certificate in your assets directory.

Step 2:

Add following line in your pubspec file.

flutter:
  assets:
     - m2mqtt_ca.crt

Step 3:

Add following block for initializing MQTT logging.

    await FlutterLogs.initMQTT(
        topic: "YOUR_TOPIC",
        brokerUrl: "", //Add URL without schema
        certificate: "m2mqtt_ca.crt",
        port: "8883");

That's it, MQTT setup is done. If only MQTT feature is required then set this flag to false to stop writing logs to storage directory:

    await FlutterLogs.initMQTT(
        writeLogsToLocalStorage: false);

Native Libraries

For Android: RxLogs
For iOS ZIPFoundation

For more details about RxLogs visit this Wiki

Author

Flutter Logs plugin is developed by Umair Adil. You can email me at m.umair.adil@gmail.com for any queries.

Support

Buy a coffe to Umair Adil, creator of this plugin.

Name		Name	Last commit message	Last commit date
Latest commit History 121 Commits
android		android
example		example
ios		ios
lib		lib
pictures		pictures
test		test
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
pubspec.yaml		pubspec.yaml

Folders and files

Latest commit

History

Repository files navigation

flutter_logs

A file based advanced logging framework for Flutter Apps (Android & iOS).

Overview

Read more about flutter_logs usage on this Medium article:

Features (Android)

Features (iOS)

Note: Work is in progress. More features will be added soon.

Install

Setting Up

Initialization

initLogs — Full Parameter Reference

Enum Values

How to log data?

Hourly Logs

Custom File Logs

Step 1:

Step 2:

Where are my logs stored?

Android:

iOS:

Export/Print Logs

Listen to export/print results:

Exports logs manually

Clear Logs

Errors/Exception Logs

Backpressure Support

Redaction & Masking (PII Protection)

Built-in Patterns

Custom Redaction Rules

Mask Types

Search & Filter Logs

Export Filtered Logs

Print Filtered Logs

Filter Types

ELK Elastic Stack Schema Support

Enable MQTT Feature

Step 1:

Step 2:

Step 3:

Native Libraries

Author

Support

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

`initLogs` — Full Parameter Reference

Packages