FileLogStorage class final

A publisher that stores logs on disk, one session per application run.

A session is a chain of chunk files <sessionId>.<index>.jsonl, each limited by maxChunkSize. The session is limited by maxSessionSize: when the limit is exceeded, the oldest chunk is deleted, so the most recent logs are always kept. On startup, sessions older than maxAge are deleted, and, if maxTotalSize is set, the oldest sessions are deleted until the rest fit into the limit. The number of chunks and sessions is not limited — only sizes are.

Logs are written in batches in the background; await flush() guarantees everything published so far is on disk. After close publications are silently ignored.

onError is called on initialization, encoding and write errors. Errors are never thrown; exceptions thrown by the callback itself are ignored.

Inheritance

Constructors

FileLogStorage({required String directory, String? sessionId, Map<String, Object?>? meta, int minLevel = LogLevels.all, int? maxTotalSize, int maxSessionSize = 10 * 1024 * 1024, int maxChunkSize = 1024 * 1024, Duration? maxAge = const Duration(days: 7), FileLogDataFormat dataFormat = FileLogDataFormat.text, LogMainTheme? theme, LoggableConfig config = const LoggableConfig(), LoggableJsonConfig jsonConfig = const LoggableJsonConfig(), void onError(Object error, StackTrace stackTrace)?})

Properties

directory → String
The directory the session files are stored in (created recursively).
final
hashCode → int
The hash code for this object.
no setterinherited
isClosed → bool
Whether close has been called.
no setterinherited
maxAge → Duration?
Sessions older than this are deleted on startup. null — keep forever.
final
maxChunkSize → int
Size limit of one chunk file, in bytes. When a chunk reaches it, the next chunk is started. Must fit into maxSessionSize at least twice.
final
maxSessionSize → int
Total size limit of one session, in bytes.
final
maxTotalSize → int?
Total size limit of all sessions together, in bytes. null — no limit.
final
meta → Map<String, Object?>?
User fields of the metadata line written as the first line of every chunk.
final
minLevel → int
final
onError → void Function(Object error, StackTrace stackTrace)?
Called when handle throws.
finalinherited
ready ↔ Future<void>
Completes when the storage is initialized: the directory is created, old sessions are cleaned up, the session id is resolved and the first chunk with the metadata line is reserved on disk. Never completes with an error. Awaiting it is optional: logs published earlier are buffered.
latefinal
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
sessionId → String
The id of the current session.
no setter
sessions → FileLogSessions
Reader for the sessions stored in directory, including the current one.
no setter
sync → bool
Whether the underlying stream controller delivers events synchronously.
finalinherited

Methods

close() → Future<void>
Closes the publisher after draining the queue: every log accepted before closing is processed, including logs published while a batch was in flight. Logs returned to the retry buffer after closing are dropped.
override
flush() → Future<void>
Completes when the queue has been fully drained.
override
handle(List<Log> logs, List<Log> retryBuffer) → Future<void>
Processes a batch of buffered logs.
override
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
publish(Log log) → void
Publishes the given log event.
override
toString() → String
A string representation of this object.
inherited

Operators

operator ==(Object other) → bool
The equality operator.
inherited