EnLogger 是一個靈活的日誌記錄套件,適用於 Flutter 應用程式,讓開發者能夠撰寫自訂的日誌訊息,而不必受限於除錯主控台或特定輸出系統。它支援 Android、iOS、Web、macOS、Windows 和 Linux 多個平台,可無縫整合至任何專案中。憑藉其可擴展的設計,EnLogger 允許使用者定義自己的日誌處理器和格式,非常適合用於除錯、監控和分析。該套件強調簡單性與控制力,讓開發者能根據自身需求精確客製化日誌行為。
適用情境
除錯應用程式流程
監控執行時行為
自定義日誌輸出路由
與外部分析工具整合
測試錯誤場景
在生產環境中的登入
主要特色
可擴充的日誌處理系統
支援多個平台
可設定的日誌格式化
不依賴除錯控制台
與現有程式碼的輕鬆整合
靈活的輸出目標
適合對象
需要自定義日誌記錄的開發人員
建構跨平台應用的團隊
需要結構化日誌的專案
具有複雜調試需求的應用程式
面向生產環境的帶有記錄功能的應用程式
使用者避免硬編碼控制台輸出
使用建議
需要手動設定日誌處理器
無內建日誌儲存或持久化
可能需要額外的設定以應對進階使用案例
未針對高頻率記錄進行優化
與完整日誌框架相比,開箱即用的功能較少
取決於使用者定義的訊息處理邏輯
原始 README
以下為關聯原始碼儲存庫的 README 原文快照,最新內容請造訪原始碼儲存庫。
En Logger
Welcome to EnLogger—a highly flexible and extensible logging system designed to adapt to your application's unique needs.
Instead of restricting you to the standard debug console, EnLogger acts as a central hub. It broadcasts your log messages to a customizable list of EnLoggerHandlers. You simply log your message once, and let your attached handlers decide where and how that data is processed.
Key Features:
Plug-and-Play Architecture:Log once, write anywhere. You can easily implement custom handlers based on your specific requirements:
Need local persistence? Implement a handler that writes logs to a local file.
Need remote crash reporting? Create a handler that pipes messages directly to Sentry, Crashlytics, or Datadog.
Lazy Evaluation: Boost your app's performance with "lazy" logging. Wrap expensive string interpolations or data serializations in closures; if the log level is disabled, the computation is completely skipped (see the Lazy messages section for details).
Zone: Automatically extract contextual data (tags) from Zone.current and attach them to every log event.
Caller info Indicates the exact location in your source code where the log was emitted
Syslog Standards: All log operations strictly adhere to the standard syslog severity levels (Emergency, Alert, Critical, Error, Warning, Notice, Info, Debug).
Ready-to-use Console Logger: Get started immediately with the included DevLogHandler, which outputs beautifully colored and formatted messages straight to your developer console.
To see these features in action, check out the example project.
Messages can include attachments such as serialized data, file contents, and more.
// error with data
logger.error(
"error",
data: [
EnLoggerData(
name: "response",
content: jsonEncode("BE data"),
description: "serialized BE response",
),
],
);
Instances
To avoid having to rewrite the prefix each time, you can create instances based on EnLogger. For instance, if you have a specific scope (like the API repository), you can instantiate a EnLogger with the prefix "API repository," and this prefix will be included in every log unless you explicitly override it.
final instLogger = logger.getConfiguredInstance(prefix: 'API Repository');
instLogger.debug('a debug message'); // [API Repository] a debug message
instLogger.error(
'error',
prefix: 'Custom prefix',
); // [Custom prefix] a debug message
Lazy messages
Lazy messages are not evaluated until at least one handler is going to write them.
Use them to avoid expensive computations when a log level is disabled (e.g. in production, where debug is often turned off).
The message closure is only called when at least one handler returns true from can(severity) for that log.
logger.lazyDebug(() => 'a lazy debug message');
// The closure is not run if debug is disabled (every handler's `can` returns `false`)
By default, can returns true for every handler, so all log levels are written unless you override it.
The message callbacks (e.g. the closure passed to lazyDebug) may be asynchronous. Handle exceptions inside the callback, otherwise they are ignored.
Tags & Zones
EnLogger can automatically extract contextual data (tags) from Dart's [Zone.current] and attach them to every log event.
By providing zoneContextKeys to the constructor, the logger will capture only the specified keys from the current execution zone.
Additionally, every logging method accepts its own tags parameter. The handlers will receive a single, merged, and sanitized map containing both the requested zone tags and the method-specific tags.
final logger = EnLogger(
zoneContextKeys: {#userId},
...
);
runZoned(
() {
// In addition to the method tags, the zoneContextKeys // values will be extracted from the zones
logger
.debug('a debug message',
prefix: 'API Repository',
tags: {'custom_key':'custom_value'},
);
},
zoneValues: {
#userId: 123,
#tenantId: 'abc'
},
);
Caller info
callerInfo captures the exact location in your source code where a log was emitted. It provides the function name, file path, and line number (e.g., AuthRepository.login (/lib/auth_repository.dart:142:5)).
While an error stackTrace shows you where an exception crashed, callerInfo pinpoints exactly where you wrote the log statement.
Because extracting stack traces is a CPU-intensive operation, this feature is disabled by default. You can explicitly enable it when initializing EnLogger:
final logger = EnLogger(includeCallerInfo: true);
Closing the logger
When you are done using an EnLogger instance, you should clean up its resources. EnLogger provides a graceful shutdown mechanism that safely stops accepting new logs and waits for any pending asynchronous writes or lazy evaluations to finish before clearing its handlers, ensuring no data is lost.
You can trigger this shutdown using two methods depending on your architectural needs:
close(): The preferred, asynchronous method. You can await it to guarantee all pending logs have been fully processed and written before proceeding.
dispose(): A synchronous wrapper around close(). It immediately marks the logger as closed and handles the graceful shutdown in the background (fire-and-forget).
Note: Both methods are safe to call multiple times (idempotent) and automatically cascade the shutdown to any child instances created via getConfiguredInstance().
Override can method to filter logs to complete skip the log evaluation.
@overrideboolcan({requiredSeverity severity, String? prefix}) {
if (isProduction) {
return severity.atLeastError; // only error and above are evaluated and written
}
returntrue; // every log is evaluated and written (default behavior)
}