FileLogStorage class final

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

Use an application-private directory. Symlinks and other non-regular entries are ignored, and each chunk is created exclusively and kept open while active. This is best-effort protection against accidental or pre-existing links, not a sandbox against another process that can race filesystem operations in the same directory.

A session is a chain of chunk files <sessionId>.<index>.jsonl. maxChunkSize is its chunk-rotation target, and maxSessionSize is its retention target: when the latter 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 its retention budget. The number of chunks and sessions is not limited.

These size settings are not hard byte ceilings. A JSON Lines record is never split, truncated or dropped solely because of its size. A record larger than maxChunkSize is written whole, and the newest chunk is never deleted, so it and the current session can also exceed maxSessionSize. Consequently, maxTotalSize cannot guarantee a hard runtime ceiling. Bound input sizes before publishing if the application requires one. Construction throws ArgumentError unless maxChunkSize is positive, maxSessionSize fits at least two chunks, and a non-null maxTotalSize is at least maxSessionSize. maxQueueSize must be null or positive.

Logs are written in batches in the background; a successfully completed await flush() guarantees everything published so far is on disk. After close publications are silently ignored. close waits for initialization, drains accepted logs, and closes the active chunk handle. Once closing starts, isClosed is immediately true and flush returns the same full-lifecycle Future as close.

Deleting the current session through FileLogSession.delete while this storage is active is unsupported. Await close before deleting it.

onError is called on initialization, encoding and write errors. Initialization and write errors that make accepted logs unavailable also make every subsequent flush and close complete with the first such error. Exceptions thrown by onError itself are ignored.

The queue between publish and the disk is bounded by maxQueueSize — 100 000 logs accepted and not yet written, the batch in flight included. At the limit it is the incoming log that is refused, so a disk that cannot keep up costs the newest logs rather than the process; everything already accepted is still written, and flush and close keep their meaning. A refused log goes to onDropped, and with no onDropped set the loss is announced on stdout rather than hidden — pass onDropped: (_) {} for silence. A log that cannot be persisted after it was accepted is also handed to onDropped. Failed writes are never retried: the storage can recover for later logs, but the durability error remains observable for the lifetime of this instance.

Implemented types

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)?, void onDropped(List<Log> logs)?, int? maxQueueSize = 100000})

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 setter
maxAge → Duration?
Sessions older than this are deleted on startup. null — keep forever.
final
maxChunkSize → int
Rotation-size target for one chunk file, in bytes.
final
maxQueueSize → int?
The most entries the queue accepts before it starts refusing them.
finalinherited
maxRetries → int
How many times a batch handed back through the retry buffer is retried before it is dropped.
finalinherited
maxSessionSize → int
Retained-size target for one session, in bytes.
final
maxTotalSize → int?
Startup retention budget for all sessions together, in bytes.
final
meta → Map<String, Object?>?
User fields of the metadata line written as the first line of every chunk.
final
minLevel → int
final
onDropped → void Function(List<Log> logs)?
Called with entries that will never be delivered.
finalinherited
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
retryDelay → Duration
How long to wait before retrying a batch that was handed back through the retry buffer.
finalinherited
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 queue hands an entry to handle on the stack of the call that published it.
finalinherited

Methods

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

Operators

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