
# 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

```dart
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}'),
                ),
              );
            },
          ),
        ),
      ]);
}
```

```yaml
# 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

- [Levels at run time and appenders](appenders.md)
- [Patterns](patterns.md)
- [All properties](properties.md)
