Log screen

A mobile or desktop app has no terminal its users can read. LogBuffer keeps the most recent records in memory, so an app can offer a log screen, a "send logs" button for bug reports, or an error badge in a debug menu. It is the logBuffer bean, and also LoggingSystem.instance.buffer.

Why

When a user reports a bug, the logs of the last minutes are the most useful thing to have, and on a phone there is no console to copy them from. The buffer keeps them, with an API made for a log viewer: live lists, filters, stable list keys, export.

Example

class LogScreen extends StatefulWidget {
  const LogScreen({super.key});

  @override
  State<LogScreen> createState() => _LogScreenState();
}

class _LogScreenState extends State<LogScreen> {
  final buffer = LoggingSystem.instance.buffer;
  var query = const LogQuery(minLevel: SpringLogLevel.info);

  @override
  Widget build(BuildContext context) => Column(children: [
        // The search box narrows the list as the user types.
        TextField(
          onChanged: (text) => setState(() => query = query.copyWith(text: text)),
        ),
        Expanded(
          child: StreamBuilder<List<SpringLogRecord>>(
            // The current list, then a new one per burst of records.
            stream: buffer.watch(query),
            builder: (context, snapshot) {
              final records = snapshot.data ?? const [];
              return ListView.builder(
                itemCount: records.length,
                itemBuilder: (context, i) => ListTile(
                  key: ValueKey(records[i].sequence), // stable while the list changes
                  title: Text(records[i].message),
                  subtitle: Text('${records[i].loggerName} · ${records[i].fields}'),
                ),
              );
            },
          ),
        ),
      ]);
}
# lib/resources/application.yml
logging:
  buffer:
    enabled: true
    capacity: 2000
  threshold:
    buffer: debug

The properties

Key Type Default Meaning
logging.buffer.enabled bool true Whether the buffer receives records
logging.buffer.capacity int, 1 to 1,000,000 1000 How many records it keeps; older ones are pushed out
logging.threshold.buffer level trace The lowest level it keeps

The API

Need API
A live filtered list buffer.watch(query): a Stream<List<SpringLogRecord>>, the current list, then one per burst of changes (many records logged in one synchronous run give one event)
A snapshot buffer.records, buffer.query(query)
Every new record buffer.onRecord, delivered synchronously during the logging call (a snack bar on an error)
Badges buffer.counts[SpringLogLevel.error], buffer.dropped (records pushed out by the capacity)
A logger filter menu buffer.loggerNames
Share or copy buffer.export(query), or buffer.export(query, pattern) with a LogPattern
Clear buffer.clear()
Resize buffer.capacity = 500

LogQuery

LogQuery(minLevel:, levels:, logger:, text:, fields:, since:) is immutable and changed with copyWith:

Criterion Matches
minLevel records of this level and above
levels records of these levels
logger records of this logger and the loggers below it
text records whose text contains it
fields records with these field values
since records logged after this time

copyWith(minLevel: null) (or levels, logger, text, since) removes that criterion. fields is the exception: copyWith(fields: null) keeps the current fields; pass const {} to remove them.

Records

A SpringLogRecord is immutable and carries time, sequence (a stable list key), level, loggerName, message, fields, error and stackTrace.

In Spring (Java)

There is no Spring counterpart of the buffer. The nearest is the actuator's logfile endpoint, which serves the log file.

See also