logd_network

pub package License: BSD-3-Clause

Network-based sinks and live observability handlers for logd.

Features HTTP batch shipping with exponential backoff retries, real-time WebSocket log streaming with automatic reconnection buffering, and an embedded local HTTP/WebSocket browser dashboard (HttpDashboardHandler / HttpServerSink).

Installation

Add logd and logd_network to your pubspec.yaml:

dependencies:
  logd: ^latest_version
  logd_network: ^latest_version

Quick Start

Use the pre-wired HttpDashboardHandler to host a local real-time browser logging dashboard with zero setup:

import 'package:logd/logd.dart';
import 'package:logd_network/logd_network.dart';

void main() {
  final dashboard = HttpDashboardHandler(
    port: 8080,
    title: 'Production Telemetry Stream',
    bufferCapacity: 200,
  );

  Logger.configure('app', handlers: [dashboard]);

  final logger = Logger.get('app.service');
  logger.info('Server started cleanly.');
  logger.warning('High memory pressure', context: {'usage': '87%'});

  // Open http://localhost:8080 in your browser to view logs in real time!
}

Features & Component Overview

Component Type Description
HttpDashboardHandler TargetHandler Pre-wired convenience handler for local browser log monitoring via HTTP/WebSocket (supports sync and .async() isolate mode).
HttpSink Physical Sink Accumulates logs in memory and ships in POST batches with exponential backoff retries.
SocketSink Physical Sink Streams logs frame-by-frame over WebSockets with offline reconnect buffering.
HttpServerSink Physical Sink Low-level server sink for hosting custom HTML/ANSI dashboards on custom ports.

Platform Compatibility

Component Role Android / iOS Windows / macOS / Linux Web / WASM Notes
HttpSink HTTP Client Batch-posts logs to remote HTTP collector endpoints via package:http.
SocketSink WebSocket Client Streams logs to remote WebSocket servers (ws://, wss://) via native & browser WebSockets.
HttpDashboardHandler HTTP/WS Server ❌ Binds a local server port on localhost. Throws UnsupportedError on Web.
HttpServerSink HTTP/WS Server ❌ Embedded server for custom HTML/ANSI dashboards. Throws UnsupportedError on Web.

1. HttpDashboardHandler (Embedded Browser Viewer)

Pre-wired, zero-configuration handler that boots a lightweight local HTTP and WebSocket server hosting an interactive real-time log viewer.

Platform Note: Designed for native/VM environments (server, desktop, CLI) where local TCP sockets can be bound. Throws UnsupportedError on Web platforms where hosting embedded servers is unsupported. For web apps, stream logs to an external collector with SocketSink or HttpSink.

// Synchronous handler (runs server on main thread)
final dashboard = HttpDashboardHandler(
  port: 8080,
  title: 'Real-Time Observability Dashboard',
);

// Or run offloaded to a background isolate (zero UI latency)
final asyncDashboard = HttpDashboardHandler.async(
  port: 8080,
  title: 'Isolate Observability Stream',
);

Logger.configure('app', handlers: [dashboard]);

2. HttpSink (Batch Shipping & Exponential Retries)

Accumulates log entries in memory and posts them in batches to remote log aggregators (e.g. Datadog, Loggly, Vector, or custom HTTP ingestion endpoints).

final httpHandler = Handler(
  formatter: const JsonFormatter(),
  sink: HttpSink(
    url: 'https://logs.example.com/api/v1/ingest',
    headers: const {'Authorization': 'Bearer token-xyz'},
    batchSize: 50,
    flushInterval: const Duration(seconds: 30),
    maxRetries: 5,
    dropPolicy: DropPolicy.discardOldest,
  ),
);

Logger.configure('app', handlers: [httpHandler]);

Drop Policies:

  • DropPolicy.discardOldest: Evicts the oldest buffered entry when capacity is reached.
  • DropPolicy.discardNewest: Rejects incoming entries when buffer is full.

3. SocketSink (Real-Time WebSocket Streaming)

Streams logs frame-by-frame over WebSockets with automatic reconnection and offline buffering.

Platform Note: Fully compatible across all platforms including Web and WASM via package:web_socket_channel. In browser targets, it connects directly using native browser WebSockets (window.WebSocket).

final wsHandler = Handler(
  formatter: const PlainFormatter(metadata: {LogMetadata.timestamp, LogMetadata.logger}),
  decorators: const [StyleDecorator(), BoxDecorator()],
  sink: SocketSink(
    url: 'wss://stream.example.com/live-logs',
    reconnectInterval: const Duration(seconds: 5),
  ),
);

Logger.configure('app.stream', handlers: [wsHandler]);

4. HttpServerSink (Low-Level Custom Dashboard Sink)

If you want to use custom formatters (like ToonFormatter), custom decorators, or custom encoders while hosting a local browser server, use HttpServerSink directly:

Platform Note: Supported on VM platforms only (server, desktop, CLI). Throws UnsupportedError on Web runtimes.

final serverSink = HttpServerSink(
  address: 'localhost',
  port: 8085,
  encoder: const HtmlEncoder(title: 'Custom Terminal Stream'),
  bufferCapacity: 500,
);

final customHandler = Handler(
  formatter: const ToonFormatter(),
  sink: serverSink,
);

Logger.configure('custom', handlers: [customHandler]);

Cross-Isolate Serialization

If transferring logger configurations to background worker isolates via Logger.exportConfig() and Logger.importConfig(), register network serializers in the worker isolate before importing:

import 'package:logd/logd.dart';
import 'package:logd_network/logd_network.dart';

void workerIsolateEntry(SendPort sendPort) {
  // Register logd_network serializers
  registerLogdNetworkSerializers();

  // Import config passed from main isolate
  Logger.importConfig(exportedJson);
}

logd_network provides an interactive CLI showcase menu in example/main.dart:

# Run interactive CLI showcase menu
dart run example/main.dart

# Or run non-blocking automated summary
dart run example/main.dart 5

Or run individual standalone showcase scripts:

dart run example/showcase/http_sink_showcase.dart
dart run example/showcase/socket_sink_showcase.dart
dart run example/showcase/http_server_sink_showcase.dart
dart run example/showcase/http_dashboard_showcase.dart

Migration from logd <=0.9.7

In logd v0.10.0, all network transport sinks (NetworkSink, HttpSink, SocketSink, HttpServerSink, HttpDashboardHandler) were permanently removed from core package:logd.

  • All network logging, HTTP batch shipping, and embedded dashboard capabilities are now exclusively provided by package:logd_network.
  • Core package:logd contains zero network dependencies (e.g. package:http, package:web_socket_channel).
  • For detailed migration instructions, see the Migration Guide.

Documentation & Monorepo

For deep-dive documentation on logd architecture, migration guides, and execution engines:

License

This package is licensed under the BSD 3-Clause License. See the LICENSE file for details.

Libraries

logd_network
Network-based sinks and observability handlers (HTTP, WebSockets, Dashboard) for the logd engine.