logd
Hierarchical logging engine with declarative subsystem control, ambient Zone context, non-blocking background isolate execution, and token-optimized AI telemetry.
Logging as an Enabling Instrument
In simple CRUD interfaces, standard console logs or formatted terminal boxes serve their purpose. But when building a complex system with continuous calculations, background isolate computations, and high-frequency state transitions, real-time observability is not a convenience—it is the only window into the health of the machine.
Available tools in the Dart ecosystem generally fell into two extremes: low-level event emitters with no formatting or sinks, or synchronous main-thread console printers that drop UI frames under load. Neither allowed declarative on-the-fly subtree reconfiguration without recompiling or restarting.
Inspired by the architectural maturity of Python's logging module and enterprise log routers like SLF4J, logd was designed from the ground up as an enabling tool: a high-performance, modular system design capable of handling real-world complexity without compromising runtime speed.
- Zero-Jank Discipline: Heavy string formatting, ANSI styling, and disk I/O belong on background worker isolates, never on the main event loop.
- Declarative Taxonomy: Subsystems are governed hierarchically with dot notation (
app.network.auth) and resolve via an invalidated resolution cache. - Ambient Scopes: Transaction context flows seamlessly through Dart Zones without polluting function signatures or class constructors.
- Dual Audience: Beautiful, compact ANSI tables for human engineers; schema-first TOON notation for autonomous AI triage agents.
Architectural Pillars & Code Anatomy
Inspect how logd provides declarative control, concurrency isolation, and token efficiency.
import 'package:logd/logd.dart';
void main() {
// 1. Establish an application-wide baseline at INFO
Logger.configure('app', logLevel: LogLevel.info);
// 2. Throttle high-frequency network polling to WARNING
Logger.configure('app.network', logLevel: LogLevel.warning);
// 3. Elevate authentication subsystem to TRACE for targeted inspection
Logger.configure('app.network.auth', logLevel: LogLevel.trace);
// 4. O(1) Subtree Pruning: Disable analytics entirely
// Calls to disabled nodes exit immediately with ZERO allocations
Logger.configure('app.analytics', enabled: false);
// 5. Pattern-based wildcard matching across dynamic subsystems
Logger.configurePattern('app.cache.*', logLevel: LogLevel.error);
}Dynamic Resolution with LoggerCache
In complex architectures with hundreds of loggers, evaluating inheritance policies on every log call introduces unacceptable overhead.
logd backs its dot-separated namespaces with an internal resolution cache (LoggerCache). When policies are updated at runtime—via an admin command, debug drawer, or network signal—only the targeted node and its descendants are invalidated.
Visual Schematics & Engineering Benchmarks
Diagrams illustrating policy inheritance, isolate concurrency boundaries, stack trace demangling, and token optimization.
Hierarchy Cascade & Resolution Flow
Hierarchical dot-notation delegation: parent policies cascade downward until overridden. The internal LoggerCache maintains O(1) resolution without per-event traversal.
120Hz Zero-Jank Frame Budget Timeline
Comparing synchronous main-thread logging (which blocks the UI event loop and causes frame drops) against background isolate worker dispatch that protects the 8.3ms frame budget.
Smart Stack Trace Demangling
Collapses dozens of framework-internal frames (e.g., Flutter rendering and pipeline bindings), immediately directing developer attention to user package call-sites and structured IR table nodes.
TOON vs JSON Token Benchmark
Empirical token comparison: TOON schema headers + tab-separated values dramatically compress structured logs, allowing LLM triage agents to analyze significantly larger telemetry batches.
A Lean Core with Specialized Satellites
Respecting low-level system hygiene: the core library carries zero external network or database dependencies. Specialization is packaged as clean satellites.
package:logd
Core Engine & Hierarchy TreeLightweight foundation, namespace inheritance, LoggerCache resolution, and intermediate representation (IR) nodes. Zero external dependencies.
package:logd_toon
Token-Optimized Telemetry for LLMsTab-Oriented Object Notation formatter. Emits schema-first tab-delimited streams saving 30-50% prompt tokens for AI triage agents.
package:logd_dio
HTTP Traffic InterceptionDio networking interceptor with sensitive credential redaction, sub-millisecond timing metrics, and automatic cURL command reproduction.
package:logd_sqlite
WAL-Mode Embedded PersistenceACID local database sink operating in SQLite WAL mode with embedded query introspection and automated table rotations.
package:logd_network
Real-Time WebSocket Server & UIEmbedded local HTTP/WebSocket daemon serving an interactive browser-based inspection dashboard during development.
package:logd_html & logd_markdown
Automated Document SynthesisGenerates structured HTML session dossiers and Markdown summaries for CI/CD test reports and crash triage archives.
Quickstart Implementation
dart pub add logdimport 'package:logd/logd.dart';
void main() {
// 1. Configure baseline isolate handler
Logger.configure('app', handlers: [ConsoleHandler.async()]);
// 2. Obtain logger instance
final log = Logger.get('app.runtime');
log.info('System initialized', context: {'status': 'operational'});
}