watchdog 0.1.1

A Flutter developer toolkit that streams HTTP requests, responses, BLoC lifecycle events, navigation, and app logs to a browser-based DevTools page in real-time.

Watchdog

A Flutter developer toolkit that streams HTTP requests, responses, BLoC lifecycle events, navigation, and app logs to a browser-based DevTools page in real-time.

Open http://<device-ip>:8888 in any browser on the same network and see everything your app is doing — no native tooling or IDE required.

Features

• Network inspector — every Chopper HTTP request/response with headers, body, status, timing, and cURL export.
• BLoC lifecycle — creation, state changes, and closure of every Bloc and Cubit, with creation stack traces.
• Navigation — push, pop, replace, remove events with a live route stack.
• Structured logging — debug / info / warning / error / critical levels, powered by Talker under the hood.
• WebSocket tracker — send, receive, and connection state events.
• GetIt scanner — broadcasts every DI registration (singletons, lazy singletons, factories).
• Cloud streaming — optionally mirror all events to a remote Watchdog Cloud server for remote debugging.
• Replay buffer — late-connecting browsers receive full event history (up to 10 000 events by default).
• Init-once safety — concurrent initialize() calls are coalesced; repeat calls are no-ops.
• Pluggable logger — bring your own WatchdogLogger implementation or use the built-in Talker-backed default.

Installation

dependencies:
  watchdog: ^0.1.0

flutter pub get

Quick start

import 'package:watchdog/watchdog.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  // 1. Initialize and start
  await Watchdog.initialize(
    config: const WatchdogConfig(
      apiBaseUrl: 'https://api.example.com',
      enableLogging: true,
    ),
  );
  await Watchdog.start();

  // 2. (Optional) Bridge your existing project logger
  // AppLogger.attachBridge(Watchdog.bridge);

  // 3. Wire DI tracking after container setup
  // await configureDependencies();
  // Watchdog.trackGetIt(getIt);

  runApp(const MyApp());
}

Wiring integrations

Chopper interceptor

ChopperClient(
  interceptors: [
    AuthInterceptor(),
    Watchdog.chopperInterceptor, // add this
  ],
);

Navigation observer

MaterialApp.router(
  routerConfig: appRouter.config(
    navigatorObservers: () => [Watchdog.routeObserver],
  ),
);

WebSocket tracking

Watchdog.socketTracker.trackSend(channel: 'wss://api.example.com/ws', data: payload);
Watchdog.socketTracker.trackReceive(channel: 'wss://api.example.com/ws', data: decoded);

Convenience logging

Watchdog.debug('Cache miss for key=$key');
Watchdog.info('Driver connected');
Watchdog.warning('GPS accuracy degraded: ${accuracy}m');
Watchdog.error('Sync failed', error: e, stackTrace: st);

Configuration

Parameter	Default	Description
apiBaseUrl	null	Shown in the DevTools header for environment identification
port	8888	Local server port
host	0.0.0.0	Bind address
enableLogging	true	Enable log events in the Logs tab
maskSensitiveHeaders	true	Masks Authorization headers in the UI
replayBufferSize	10000	Max events retained for late-connecting clients
enabled	null	null = kDebugMode; set true to force-enable in release
cloud	null	WatchdogCloudConfig for remote streaming

Custom logger

Implement WatchdogLogger to integrate with your own logging stack:

class MyLogger implements WatchdogLogger {
  @override
  void log(WatchdogLogLevel level, String message, {String? title, Object? error, StackTrace? stackTrace}) {
    // your implementation
  }

  // Convenience methods are inherited from WatchdogLogger.
}

await Watchdog.initialize(
  dependencies: WatchdogDependencies(logger: MyLogger()),
);

Cloud streaming

await Watchdog.initialize(
  config: const WatchdogConfig(
    cloud: WatchdogCloudConfig(
      serverUrl: 'wss://watchdog-cloud.example.com',
      apiKey: 'your-api-key',
      appName: 'my-app',
    ),
  ),
);

Public API summary

Accessor	Type	Description
Watchdog.initialize()	Future<void>	One-time setup
Watchdog.start()	Future<void>	Opens server + cloud
Watchdog.stop()	Future<void>	Pauses capture
Watchdog.dispose()	Future<void>	Full teardown
Watchdog.logger	WatchdogLogger	Active logger instance
Watchdog.bridge	WatchdogLoggerBridge	Legacy logger adapter
Watchdog.blocObserver	WatchdogBlocObserver	BLoC lifecycle observer
Watchdog.routeObserver	WatchdogRouteObserver	Navigation observer
Watchdog.chopperInterceptor	WatchdogChopperInterceptor	HTTP interceptor
Watchdog.socketTracker	WatchdogSocketTracker	WebSocket tracker
Watchdog.trackGetIt()	void	Scans GetIt container
Watchdog.isInitialized	bool	Init state
Watchdog.isRunning	bool	Server state

License

MIT - see LICENSE.