zero_inspector_kit 1.1.0

A Flutter plugin for in-app developer console with network request viewing, logging, database inspection, and route tracking.

Zero Inspector Kit

A powerful Flutter plugin for in-app developer console, providing real-time debugging tools including network request inspection, logging, database viewing, memory monitoring, and route tracking.

🌐 Official Website

🔗 View on GitHub

Features

• Zero Invasion: Integrate with just 1 line of code, no need to modify any existing project code.
• Network Inspector: Capture and view all HTTP requests in real-time, including request/response headers, body, status codes, and latency. Supports modifying request body and headers via interceptor rules (for POST/PUT/PATCH requests).
• Logging System: Capture application logs automatically from print() calls, Flutter errors/exceptions, and custom log methods. Supports multiple levels (verbose, debug, info, warning, error) and third-party log library integration.
• Database Viewer: Inspect SQLite and other databases with support for custom database providers.
• Memory Monitor: Real-time memory monitoring with trend chart, Dart Heap details, Native memory breakdown (Android PSS / iOS physicalFootprint), memory leak detection, image cache monitoring, and app storage statistics. Master switch to avoid performance overhead.
• Route Tracker: Monitor navigation history and current route information.
• Floating Button: Accessible floating inspector button with breathing animation that slides in/out from the edge of the screen.
• Modern UI: Beautiful dark theme with gradient design, customizable colors via centralized theme configuration.
• Cross-platform: Works on Android and iOS.

Installation

Pub.dev (Recommended)

Add the following to your pubspec.yaml:

dependencies:
  zero_inspector_kit: ^1.1.0

GitHub

Alternatively, you can install from GitHub:

dependencies:
  zero_inspector_kit:
    git:
      url: https://github.com/zero-labsco/zero_inspector_kit.git
      ref: main

Usage

Zero Invasion Integration (Recommended)

Integrate with just 1 line of code, no need to modify any existing project code:

import 'package:flutter/material.dart';
import 'package:zero_inspector_kit/zero_inspector_kit.dart';

void main() {
  // Single line: Initialize inspector, capture print() via Zone, and display floating button
  ZeroInspectorKit.runAppWithInspector(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      navigatorObservers: [InspectorRouteObserver()],
      home: Scaffold(
        appBar: AppBar(title: const Text('App')),
        body: const Center(child: Text('Hello World')),
      ),
    );
  }
}

Zero Invasion Explanation:

After integration, the inspector automatically does the following without modifying any other project code:

• ✅ Log Capture: Automatically captures all print(), debugPrint() calls and Flutter errors via Zone
• ✅ Network Interception: Automatically intercepts all http package and Dio network requests via HttpOverrides (Dio uses HttpClient by default).
• ✅ Database Scan: Automatically scans and registers SQLite databases
• ✅ Floating Button: Automatically displayed via Overlay, no need to manually add any components
• ✅ Route Tracking: Monitors navigation history via InspectorRouteObserver (automatically injected into MaterialApp)

Production Build: The inspector is automatically disabled in release mode. You don't need to remove any code - Flutter's tree-shaking will remove all inspector-related code from production builds.

Alternative Integration (Two Lines)

If you prefer more control, you can use the two-line approach:

void main() {
  ZeroInspectorKit.init();
  runApp(ZeroInspectorKit.wrapApp(const MyApp()));
}

Logging

The logger automatically captures logs from multiple sources once started:

InspectorLogInterceptor.instance.start();

Auto-captured logs:

• print() and debugPrint() calls
• Flutter framework errors and exceptions
• Unhandled exceptions caught by runZonedGuarded

Manual logging (Optional):

For more precise log level control, you can use the inspector's log methods. This is optional and does not affect auto-capture functionality:

InspectorLogInterceptor.instance.verbose('Verbose log');
InspectorLogInterceptor.instance.debug('Debug log');
InspectorLogInterceptor.instance.info('Info log');
InspectorLogInterceptor.instance.warning('Warning log');
InspectorLogInterceptor.instance.error('Error log');

Third-party log library integration (Automatic):

No configuration needed! The plugin automatically captures logs from all third-party logging libraries (e.g., logger, flutter_logger, logcat) that use print() or debugPrint().

How it works: The plugin captures all print() calls by overriding debugPrint and using Zone mechanism. Most third-party logging libraries internally output logs via print().

These logs are categorized as INFO level since each library has its own level indicators (emoji, prefixes, etc.) that users can identify from the log content.

Bidirectional Sync (Optional):

If you need to sync inspector-captured logs to your third-party logging library (make inspector logs also appear in your logging service), use the onLogCaptured callback:

import 'package:logger/logger.dart';

final logger = Logger();

InspectorLogInterceptor.instance.onLogCaptured = (entry) {
  logger.log(
    _mapLogLevel(entry.level),
    '${entry.tag != null ? '[${entry.tag}] ' : ''}${entry.message}',
  );
};

Network Requests

All HTTP requests (both http package and Dio) are automatically intercepted via HttpOverrides after initialization. No additional setup is required!

http package:

import 'package:http/http.dart' as http;

// GET request (automatically captured)
final response = await http.get(
  Uri.parse('https://api.example.com/data'),
);

// POST request (automatically captured)
final response = await http.post(
  Uri.parse('https://api.example.com/data'),
  body: {'key': 'value'},
);

Dio (zero-invasion):

import 'package:dio/dio.dart';

final Dio dio = Dio();

// GET request (automatically captured)
final response = await dio.get('https://api.example.com/data');

// POST request (automatically captured)
final response = await dio.post(
  'https://api.example.com/data',
  data: {'key': 'value'},
);

Note: Dio uses IOHttpClientAdapter by default, which internally uses dart:io's HttpClient. This allows the inspector to capture Dio requests automatically via HttpOverrides without any additional configuration.

Network Request Interceptor

The inspector supports intercepting and modifying network requests via rules. This is useful for testing different request parameters without modifying app code.

Workflow:

1. Send a request normally (it will be captured in the Network panel)
2. Open the request detail and tap the Interceptor icon
3. Configure the modification rule (URL pattern, HTTP method, request modifications)
4. Save the rule — subsequent matching requests will use the modified parameters

Supported modifications:

• Request body and request headers
• Only for requests with body (POST, PUT, PATCH, etc.)
• GET requests are view-only and cannot be modified

Why can't GET requests be modified?

• The interceptor currently supports modifying request body and headers only
• GET requests don't have a request body
• Modifying GET request parameters would require URL modification
• URL modification may cause unexpected issues with request routing and parameter encoding

Rule matching:

• URL pattern matching (exact match or regex)
• HTTP method filtering (GET, POST, PUT, DELETE, PATCH, HEAD, or Any)

Note: When no rules are configured or rules are disabled, all requests are sent normally without any modification.

Database Provider

DatabaseRegistry.instance.registerProvider(SqliteDatabaseProvider());

Memory Monitor

The memory monitor provides comprehensive memory analysis with a master switch to control data collection (off by default to avoid performance overhead).

Master Switch:

• Top switch in the Memory panel controls whether monitoring is enabled
• When disabled: all timers stop, VM Service connection is cleared (no WebSocket overhead)
• When enabled: starts data collection and attempts VM Service connection

Memory Trend Chart:

• Real-time line chart with 2-minute history window (240 snapshots × 500ms)
• Switchable between 4 metrics: Process RSS / Dart Heap / New Space / Old Space

Dart Heap Overview (requires VM Service):

• Heap Usage / Capacity / External usage with progress bar
• New/Old space detailed breakdown (Usage / Capacity / External)
• Manual GC trigger button (disabled when VM Service unavailable)

Native Memory (100% available on real devices):

• Android: Total PSS, Dalvik PSS, Native PSS, Native Private Dirty, Device Memory status
• iOS: Physical Footprint, Compressed memory, Process RSS, Device available memory
• Low memory warning indicator

Memory Leak Detection (based on Dart 2.17+ WeakReference):

• Register objects for leak tracking via trackObject() API
• Four-state transition: tracking → verifying → leaked / released
• Auto-trigger GC verification after exceeding expected release time
• UI shows suspected leaks (red), tracking objects, and released objects

// Register an object for leak tracking
MemoryInspectorService.instance.trackObject(
  myBloc,
  tag: 'HomePage_myBloc',
  expectedReleaseAfter: Duration(seconds: 60),
);

// Cancel tracking
MemoryInspectorService.instance.untrackObject(myBloc);

// Clear all records
MemoryInspectorService.instance.clearLeakRecords();

Image Cache Monitoring:

• Real-time display of image cache size and count
• Shows pending (loading) and live (in use) image counts
• Visual progress bar of cache usage
• One-click clear all image cache

App Storage Statistics:

• Documents directory size
• Temp cache directory size
• Total database file size
• One-click clear app temp cache

⚠️ Important: VM Service availability

When debugging via PC with flutter run, Dart VM Heap data may be unavailable (VM: OFF).

Reason: When using flutter run to debug via PC, the flutter tool sets up port forwarding between PC and device via adb reverse, allowing PC-side DevTools to access the device's VM Service. However, Service.getInfo() returns a serverUri from PC's perspective; when the app process internally accesses 127.0.0.1:PC_port, the device doesn't have that port listening locally, resulting in Connection refused and VM Service showing OFF.

Does not affect actual usage: When opening the debug app directly without PC connection (no flutter tool involved), VM Service listens directly on the device's local port, the app can connect normally, and Dart Heap data displays correctly.

Fallback: When VM Service is unavailable, Native memory (Android PSS / iOS physicalFootprint) still displays normally, and process RSS is always available. Only Dart Heap details and manual GC are unavailable.

Custom Database Provider

To add support for other databases, implement the DatabaseProvider interface:

class MyCustomDatabaseProvider implements DatabaseProvider {
  @override
  String get name => 'CustomDB';

  @override
  Future<List<DatabaseInfo>> getDatabases() async {
    // Return list of databases
    return [];
  }

  @override
  Future<QueryResult> queryTable(String dbPath, String tableName, {int limit = 50}) async {
    // Execute query and return results
    return QueryResult(columns: [], rows: []);
  }
}

// Register the provider
DatabaseRegistry.instance.registerProvider(MyCustomDatabaseProvider());

API Reference

FloatingInspectorButton

Parameter	Type	Description
enabled	bool	Whether the inspector is enabled (default: true, automatically disabled in release mode)

ConditionalInspector

A convenience widget that automatically shows/hides the inspector based on build mode.

ConditionalInspector(
  child: YourAppWidget(),
)

Parameter	Type	Description
child	Widget	The child widget
enabled	bool	Whether the inspector is enabled (default: true)

InspectorLogInterceptor

Method	Description
start()	Start capturing logs
stop()	Stop capturing logs
log(level, message, tag)	Add a log entry
verbose(message, tag)	Add verbose log
debug(message, tag)	Add debug log
info(message, tag)	Add info log
warning(message, tag)	Add warning log
error(message, tag)	Add error log

Property	Type	Description
onLogCaptured	void Function(LogEntry)?	Callback when a log is captured, used for third-party log library integration

InspectorRouteObserver

Navigator observer for tracking route changes.

runInspectorApp

A helper function to run your app with the inspector Zone, enabling automatic print() capture.

runInspectorApp(VoidCallback appRunner)

Parameter	Type	Description
appRunner	VoidCallback	The function to run your app (usually runApp)

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.