Читать на русском.
structured_log
Structured logging for Dart and Flutter — from a line in your app's
console to a searchable, shared log store for your whole team.
Inspired by Python's structlog. Documentation:
structured-log.openidealab.com.
Why
A log line like "User 42 logged in from 127.0.0.1" is easy to write and
hard to use: you can't filter it by user, count it by IP, or follow one
request through it without regular expressions. structured_log records
events with data instead — user_login {user_id: 42, ip: 127.0.0.1} —
so the same entry reads well in a terminal, parses as JSON, and can be
searched by any field.
The project covers the whole path such an entry travels:
- Write it — a small, dependency-free core library for Dart and Flutter.
- Get it for free — adapters that log what
bloc, riverpod, dio,
http, go_router, auto_route and cherrypick already do in your app,
the queries of a drift database, every request a shelf server answers,
and a bridge for every library that logs through package:logging.
- See it on the device — a drop-in log viewer screen in Material,
Fluent or Cupertino style.
- Collect it — a self-hosted server that receives logs from every
install of your app, stores them, and lets your team search and tail
them live in a web admin.
Steps 1–3 work entirely inside your app, with no server at all. Step 4 is
optional, and adding it doesn't change a single logging call.
Features
Structured logging core
- Events with context —
log.info('user_login', context: {...});
bind() attaches fields to a logger (immutably), withCorrelation()
adds typed session/request/operation ids.
- Processors — enrich, transform or drop entries before output.
- Secret redaction — passwords, tokens and keys masked by field name,
JWTs and card numbers by value.
- Many outputs at once — pretty JSON, JSON lines, logfmt, colored
console, file, rotating file, async file, or your own function; each sink
with its own level and category filter, switchable at runtime.
- Safe by design — a log call never throws, and an unencodable value
(
DateTime, an exception) costs one field, not the entry.
- Everywhere Dart runs — VM, Flutter, and the web; no runtime
dependencies beyond
meta.
In-app log viewer for Flutter
- A ready-made screen or embeddable widget: live list, search, level and
category filters, pause, clear, entry details with copy.
- Three design systems — Material 3, Fluent UI (WinUI-style) and
Cupertino (iOS-style) — each adaptive: bottom sheet or pushed screen
on phones, master-detail on tablets and desktop.
- A headless core (
LogBuffer, LogViewerController) to build your own UI.
Integrations
| Library | What gets logged | Category |
|---|
bloc / flutter_bloc | creation, events, transitions, errors, closing of every bloc and cubit | bloc |
riverpod / flutter_riverpod | creation, updates, failures, removal of every provider; a failure is logged once | riverpod |
dio | every request and its outcome, level by status code | http |
package:http | the same, as a wrapping http.Client, without buffering bodies | http |
go_router | navigation with route pattern, redirects, routing errors | navigation |
auto_route | navigation with route name and pattern, tab switches; tokens redacted | navigation |
cherrypick | DI scopes, modules, cycles, resolve errors — never an instance | di |
drift | every query with its SQL, duration and rows, slow ones flagged, failures with their stack — argument values off | db |
package:logging | every record of every library that logs through it, with its level, error and stack trace | logging |
shelf (server) | every request a server answers, level by status code; handlers get a logger bound to the request_id, returned in X-Request-Id | http |
HTTP and navigation adapters redact auth headers, cookies, and token-like
query parameters by default; bodies are off unless enabled, and masked by
field name when they are — except on the server, where structured_log_shelf
never writes them at all.
Self-hosted log server and admin client
- Shipping —
RemoteSyncLogOutput batches entries, retries with
backoff, caps its buffer, and never blocks the code that logged.
- Ingest, search, live tail — a full-text and per-field query API, and
a Server-Sent Events stream with catch-up after reconnects.
- Multi-tenancy — groups own projects; each project has its own secret
keys, quotas and retention window.
- Access control — users, teams, and per-scope roles
(
admin/owner/user); JWT sessions with an HttpOnly refresh cookie
in the browser; rate limiting on the auth endpoints; an audit log of who
changed what.
- Simple to run — one Dart process with an embedded SQLite file by
default, PostgreSQL when you need it; docker-compose and Kubernetes
manifests included.
- Web admin — a Fluent UI app (English/Russian) for managing groups,
projects, keys, users and teams, and for searching and live-tailing logs.
How it fits together
flowchart LR
subgraph app["Your Dart / Flutter app"]
A["Adapters<br/>bloc · riverpod · dio · http · go_router · auto_route · cherrypick · drift · logging · shelf"] --> C["structured_log"]
Y["Your code"] --> C
C --> O["Console / file"]
C --> V["In-app log viewer"]
C --> R["RemoteSyncLogOutput"]
end
R -- "HTTP, batched" --> S["structured_log_server<br/>SQLite or PostgreSQL"]
S -- "query API · SSE" --> W["Admin client (web)"]
Everything inside the box works on its own; the server side is added only
when you want logs collected centrally.
Quick start
Add the core library:
dart pub add structured_log
Log events with data:
import 'package:structured_log/structured_log.dart';
void main() {
final log = getLogger().bind({'service': 'checkout'});
log.info('user_login', context: {'user_id': 42, 'ip': '127.0.0.1'});
}
Ship the same entries to your server — alongside the console, without
touching any logging call:
import 'package:structured_log/structured_log.dart';
import 'package:structured_log_remote_sync/structured_log_remote_sync.dart';
final output = RemoteSyncLogOutput(
serverUrl: 'https://logs.example.com',
projectSecretKey: 'slk_...',
);
StructlogConfiguration.configure(sinks: [
LogSink(name: 'console', output: coloredConsoleOutput),
LogSink(name: 'server', output: output, minLevel: LogLevel.info),
]);
Run the server and the admin client with docker-compose, then open
http://localhost:8080:
cd deploy && ./deploy.sh
Next steps: the Embedding Guide for the
in-app viewer and adapters, the Administrator Guide
for running the server, the User Guide for
the admin client.
Packages
The adapters are pre-releases. structured_log_http is the former name of
structured_log_remote_sync and is discontinued. The repository also holds
the admin client's component library
(structured_log_admin_ui) and
end-to-end tests across the whole system (packages/e2e).
Status
The libraries are published and in use. The server and the admin client
are working software — ingestion, search, live streaming, multi-tenancy,
access control and auditing are all there — but not feature-complete:
self-service registration, password recovery and email verification are
specified and not built yet. Progress is tracked in
openspec/changes/add-structured-log-server/tasks.md.
Documentation
- structured-log.openidealab.com —
the documentation site, English and Russian.
- docs/guides/ — task-oriented guides: embedding
(no server), user, administrator/DevOps, developer, contributor.
- docs/ — how the server system is designed: API, auth
and RBAC, storage, live streaming, operations.
- Each package's README — installation and full API reference.
Contributing
This is a Melos + FVM
workspace. Packages are grouped by kind: emb/ for libraries embedded in
apps, backend/ for the server, frontend/ for the admin client, and
packages/ for the end-to-end tests.
dart run melos bootstrap
dart run melos run lint
dart run melos run test
Start with the Contributor Guide;
AGENTS.md is the full reference for commands, conventions,
versioning and CI. Design decisions and requirements live in
openspec/.
License
MIT — see LICENSE.
