diff --git a/CHANGELOG.md b/CHANGELOG.md index b05ae2b..f3e8593 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,7 @@ +## 0.0.6 + +* Add additional docs + ## 0.0.5 * Fix some documentation issues diff --git a/README.md b/README.md index 62be00d..5999462 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,7 @@ # TheLogger +[![Analyze and test all](https://github.com/nesquikm/the_logger/actions/workflows/analyze-and-test.yaml/badge.svg)](https://github.com/nesquikm/the_logger/actions/workflows/analyze-and-test.yaml) + A modular logging library for Flutter. ## Features @@ -13,7 +15,7 @@ A modular logging library for Flutter. ## Getting started -To use this package, add `the_logger` as a [dependency in your pubspec.yaml file](https://flutter.dev/docs/development/packages-and-plugins/using-packages). +To use this package, add `the_logger` and `logging` as a [dependency in your pubspec.yaml file](https://flutter.dev/docs/development/packages-and-plugins/using-packages). ## Usage @@ -26,24 +28,113 @@ import 'package:the_logger/the_logger.dart'; Get an instance of the logger and initialize it: ```dart -TheLogger.i().init(); +await TheLogger.i().init(); ``` TheLogger is a singleton, so you can get the same instance anywhere in your app: ```dart -instance = TheLogger.i(); +final instance = TheLogger.i(); +``` + +This should be done as early as possible in your app, and only once. Before calling `init()` second time, you should call `dispose()` method. + +You can define retain strategy for logs. For example: + +```dart +TheLogger.i().init(retainStrategy: { + Level.ALL: 200, // ALL records will be deleted after 200 sessions + Level.INFO: 100, // records with INFO and higher level retained for 300 sessions + Level.SEVERE: 50, // records with SEVERE and higher level retained for 350 sessions +}); +``` + +Logs are separated by sessions. By default, TheLogger starts a new session every time you call `init()` method (but you can change this behavior by passing `startNewSession: false` to `init()` method): + +```dart +TheLogger.i().init(startNewSession: false); ``` -You can start a new logging session by calling: +You can start a new session manually by calling: ```dart TheLogger.i().startSession(); ``` -It is convininet method to sepatare logs by sessions. By default, TheLogger starts a new session every time you call `init()` method (but you can change this behavior by passing `startNewSession: false` to `init()` method). `startSession()` can be called multiple times, for example when app resumes from background (see example). +`startSession()` can be called multiple times, for example when app resumes from background (see example). + +There is a way to append session start log message with custom string (for example, you can add application version) or change session start log message level: + +```dart +TheLogger.i().init( + sessionStartExtra: $appVersion, + sessionStartLevel: Level.FINE, // default is Level.INFO +); +``` + +To enable or disable console logging and whethe to store logs in database, use: + +```dart +TheLogger.i().init( + consoleLogger: false, + dbLogger: false, +); +``` + +There is a way to capture logs that will be sent to console by providing callback function `consoleLoggerCallback`: -Also you can configure retain strategy, add custom loggers etc. Just check documentation for `init()` method. +```dart +TheLogger.i().init( + consoleLoggerCallback: ( + String message, { + DateTime? time, + int? sequenceNumber, + int level = 0, + String name = '', + Zone? zone, + Object? error, + StackTrace? stackTrace, + ) { + // do something with the record + }, +); +``` + +You can add custom loggers (for example for sending logs to server): + +```dart +TheLogger.i().init( + customLoggers: [ + remoteLogger, + anotherLogger, + ], +); +``` + +To log a message, use [logging](https://pub.dev/packages/logging) package method: + +```dart +final log = Logger('MyClass'); +log.info('This is an info message'); +log.warning('This is a warning message'); +``` + +To write all logs to compressed file call `writeAllLogsToJson` method: + +```dart +final filePath = await TheLogger.i().writeAllLogsToJson(); +``` + +This method returns a path to the file with logs. You can send this file to server, ask user to send it to you, or do whatever you want with it. + +For debugging purposes, you can get all logs from database and clear all logs from database: + +```dart +final logsAsString = await TheLogger.i().getAllLogsAsString(); +final logsAsList = await TheLogger.i().getAllLogs(); +final logsAsAsMaps = await TheLogger.i().getAllLogsAsMaps(); +final logsAsAsMaps = await TheLogger.i().clearAllLogs(); +``` ## Testing diff --git a/example/pubspec.lock b/example/pubspec.lock index 6119d2c..7e2a6f5 100644 --- a/example/pubspec.lock +++ b/example/pubspec.lock @@ -318,7 +318,7 @@ packages: path: ".." relative: true source: path - version: "0.0.4" + version: "0.0.6" typed_data: dependency: transitive description: diff --git a/example/pubspec.yaml b/example/pubspec.yaml index 4aead99..fe439e8 100644 --- a/example/pubspec.yaml +++ b/example/pubspec.yaml @@ -38,6 +38,7 @@ dependencies: logging: ^1.2.0 the_logger: path: ../ + version: 0.0.6 dev_dependencies: # The "flutter_lints" package below contains a set of recommended lints to diff --git a/lib/src/the_logger.dart b/lib/src/the_logger.dart index 185a047..4033e87 100644 --- a/lib/src/the_logger.dart +++ b/lib/src/the_logger.dart @@ -39,7 +39,7 @@ class TheLogger { /// So, examples: /// /// { - /// Level.ALL: 200, // ALL records with be deleted after 200 sessions + /// Level.ALL: 200, // ALL records will be deleted after 200 sessions /// Level.INFO: 100, // records with INFO and higher level retained for 300 sessions /// Level.SEVERE: 50, // records with SEVERE and higher level retained for 350 sessions /// } diff --git a/pubspec.yaml b/pubspec.yaml index e34779f..8bc8956 100644 --- a/pubspec.yaml +++ b/pubspec.yaml @@ -1,6 +1,6 @@ name: the_logger description: "A modular logging library for Flutter: supports multiple loggers, storage and filters" -version: 0.0.5 +version: 0.0.6 homepage: https://github.com/nesquikm/the_logger environment: