ispect 5.0.0-dev39

In-app observability and QA diagnostics toolkit for Flutter, with logs, network tracing, layout inspection, exports, and redaction.

ISpect is an internal pre-release diagnostics toolkit for Flutter and Dart. It is built for development, QA, staging, dogfooding, and design-review builds — not for public production releases. It provides a visual debug panel, structured logging, network monitoring, database tracing, widget-tree inspection, export/import, and data redaction, with compile-time gating so the toolkit is inactive unless ISPECT_ENABLED=true is provided.

Live web demo — drag and drop exported log files to explore them in the browser.

Preview

Desktop log viewer and standalone web demo.

Inspector Render tree, layout, spacing, transforms.	Color picker Read on-screen colors and compare values.
JSON viewer Inspect structured payloads without leaving the app.	Export and share Send sessions and logs for debugging or QA.

Mobile showcase

Why ISpect?

ISpect is designed for the pre-release gap between local debugging and shipped production: QA builds, staging builds, dogfooding, and design-review builds where testers, designers, and developers need to inspect what happened inside the app without attaching a debugger. When ISPECT_ENABLED is not defined at compile time, ISpect entry points become const-guarded no-ops and are eligible for Dart tree-shaking.

Capability	What it does
Release-gated builds	Compile-time guard keeps the toolkit inactive unless explicitly enabled
Visual debug panel	Draggable overlay with custom actions, badges, and the log viewer
Widget inspector	Tap any widget to read its render box, decorations, constraints, and transforms
Structured logs	Typed entries with levels, categories, filtering, history, and export/import
Network capture	Request / response / error capture for Dio, http, and WebSocket clients
Database tracing	Passive observability for any storage driver via a single dbTrace extension
BLoC observer	Event / state / transition / error forwarding into the log pipeline
Automatic redaction	Tokens, passwords, PII, and credit-card data masked before they reach logs
Observer hooks	Forward selected events to internal tools through your own adapter
12 languages	en, ru, kk, zh, es, fr, de, pt, ar, ko, ja, hi

How it differs

Tool	Best for	Where ISpect fits
Flutter DevTools	Local profiling, widget inspection, memory, CPU, and debugger workflows	ISpect runs inside QA/staging builds and can export a diagnostic session without a connected IDE
Sentry / Crashlytics	Production crash reporting, release health, alerts, and long-term telemetry	ISpect is for pre-release in-app inspection before the app ships
Dio interceptors / loggers	Request logs and console output	ISpect correlates logs, network, database, BLoC, navigation, export, and visual inspection in one viewer

Data handling

ISpect captures the diagnostic streams you explicitly enable: logs, network metadata, optional payloads, database traces, BLoC events, navigation events, and exports. Network redaction is enabled by default, and the shared redaction engine covers common auth headers, tokens, cookies, credentials, PII, and financial fields. Application-specific identifiers should be added to the redaction configuration by the team that owns the data model.

Unlike a plain log viewer, ISpect uses the same redaction pipeline across supported network interceptors, log export, clipboard helpers, and observer boundaries. This gives diagnostic workflows safer defaults while keeping capture scope and external forwarding explicit.

For shared dev, QA, staging, dogfooding, and design-review builds:

• keep body/header capture limited to what the team actually needs;
• add project-specific redaction keys for tenant IDs, internal tokens, account numbers, and business identifiers;
• handle exported sessions according to the data they contain;
• review observer adapters before forwarding logs to internal tools;
• keep production release pipelines free of --dart-define=ISPECT_ENABLED=true; passing the flag is an explicit opt-in for internal builds.

See docs/SECURITY.md for the data-handling policy and recommended rollout checklist.

Minimal safe setup

Start with the UI shell and metadata-only diagnostics, then enable deeper capture only for the pre-release problem you are investigating.

1. Add ispect and wrap the app with ISpect.run(...) / ISpectBuilder.wrap(...).
2. Run internal builds with --dart-define=ISPECT_ENABLED=true.
3. Keep production release jobs free of that flag.
4. Enable network/database/BLoC modules one at a time.
5. Keep body/header capture off until payload details are needed.
6. Add project-specific redaction keys before sharing exported sessions outside the development team.

The ISpect toolkit

ISpect is a modular monorepo. Install only what your project needs — each package works independently.

Package	What it does
ispect	Flutter UI — debug panel, log viewer, navigation observer, inspector integration
ispect_layout	Visual layout inspector — sizes, constraints, decorations, compare mode, color picker
ispectify	Pure-Dart logging core — typed log entries, filtering, tracing, observers
ispectify_dio	Dio HTTP interceptor with automatic redaction
ispectify_http	http package interceptor with automatic redaction
ispectify_ws	WebSocket traffic capture with automatic redaction
ispectify_db	Database operation tracing (SQL, ORM, KV stores)
ispectify_bloc	BLoC event / state / transition observer

Release channel

The 5.0.0-dev line is a pre-release channel for teams validating the upcoming 5.x architecture and package split. If your dependency policy allows only stable packages, pin a stable version from pub.dev until 5.0.0 is released.

Project maturity

Current public signals:

• Release channel: 5.0.0-dev is the active 5.x validation line; teams that require stable-only dependencies can stay on the latest stable 4.x release until 5.0 is published.

• SDK baseline: Dart >=3.6.0 <4.0.0; Flutter packages are tested against the pinned Flutter SDK used in CI, with latest stable tracked as an advisory signal.

• Release safety: production-safety CI builds a release APK without ISPECT_ENABLED and checks the disabled footprint.

• Data handling: supported network capture, exports, clipboard helpers, cURL generation, and observer boundaries share the same redaction pipeline.

• Migration policy: deprecated APIs are documented with replacements and removal targets.

• Security and data handling

• Compatibility policy

• Deprecations and migration notes

• Quality gates

• Performance scope

• Use cases

• Roadmap

Performance scope

When ISPECT_ENABLED is omitted, ISpect entry points are inactive and eligible for tree-shaking. In internal QA/staging builds where ISpect is enabled, runtime cost depends on what the team turns on: metadata-only logging is lighter than body capture, database tracing, or high-volume BLoC/event streams.

For noisy flows, use focused capture, filters, sampling, and bounded history. Public benchmark numbers are intentionally not claimed until they are measured and reproducible across supported Flutter versions.

Quick start

dependencies:
  ispect: ^5.0.0-dev39

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

void main() {
  ISpect.run(() => runApp(const MyApp()));
}

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

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      localizationsDelegates: ISpectLocalizations.delegates(),
      navigatorObservers: ISpectNavigatorObserver.observers(),
      builder: (_, child) => ISpectBuilder.wrap(child: child!),
      home: const HomePage(),
    );
  }
}

# Development — toolkit active.
flutter run --dart-define=ISPECT_ENABLED=true

# Release — omit the flag so ISpect remains inactive.
flutter build apk

For package-specific guides (Dio, http, WS, DB, BLoC, layout inspector) see the individual package READMEs linked in the table above.

Production safety

ISpect is flag-gated. When ISPECT_ENABLED is not defined at compile time, ISpect.run(), ISpectBuilder, and ISpectLocalizations.delegates() become const-guarded no-ops. Because the disabled path is known at compile time, release builds are eligible for Dart's tree-shaker to remove the inactive toolkit code.

ISPECT_ENABLED is a build-time decision, not a runtime toggle. ISpect does not enable itself in production; release pipelines opt in only if they explicitly pass --dart-define=ISPECT_ENABLED=true.

# Development — toolkit active.
flutter run --dart-define=ISPECT_ENABLED=true

# Release — omit the flag so ISpect stays inactive.
flutter build apk

For environment-aware control:

import 'package:flutter/foundation.dart';

class ISpectConfig {
  static const bool isEnabled = bool.fromEnvironment(
    'ISPECT_ENABLED',
    defaultValue: kDebugMode,
  );

  static const String environment = String.fromEnvironment(
    'ENVIRONMENT',
    defaultValue: 'development',
  );

  static bool get shouldInitialize => isEnabled && environment != 'production';
}

Release checklist:

• keep production release jobs free of --dart-define=ISPECT_ENABLED=true;
• keep debug-only setup inside ISpect.run(...) / ISpectBuilder.wrap(...) entry points;
• prefer environment-aware guards such as ENVIRONMENT != 'production' for internal staging builds;
• verify generated artifacts if your compliance process requires binary evidence.

Measured impact on an obfuscated release APK (no --dart-define=ISPECT_ENABLED): 6 residual "ispect" strings vs. 276 in a development build. Treat this as a release-footprint check, not a promise that every textual reference disappears from the binary.

Repository

This repository is a monorepo containing every package above plus a standalone web-based log viewer, with shared tooling for versioning, publishing, and doc sync. See bash/README.md for the automation stack and docs/VERSION_MANAGEMENT.md for the release workflow.

Documentation workflow

Each package README is generated from a per-package source in docs/readme/. Shared fragments (header, footer, install matrix, redaction block, production-safety block) live in docs/readme/_partials/. Regenerate with ./bash/build_readme.sh; verify in CI with ./bash/build_readme.sh --check. Do not edit packages/*/README.md by hand — edits are overwritten on the next build.

Contributing

Contributions are welcome. See CONTRIBUTING.md for guidelines, and open issues or pull requests at the ISpect repository.

License

MIT — see LICENSE.

---