🔍 device_diagnostics

A Flutter package for opt-in device diagnostics, performance monitoring, network instrumentation, and PDF diagnostic reports. 📊

Monitor your Flutter application's performance, track network activity, inspect device metrics, and generate diagnostic reports — all through a single package. 🚀

✨ Features

📱 Device information — model, manufacturer, operating system, and architecture where available.
⚡ CPU monitoring — process CPU usage estimates where supported.
🧠 Memory monitoring — track application memory usage.
🌡️ Thermal monitoring — inspect device thermal state where supported.
🌐 Network instrumentation — track HTTP request and response body bytes through the provided client.
🎬 Frame monitoring — observe frame performance and estimate dropped frames.
🧭 Route tracking — associate diagnostic activity with application screens.
📄 PDF reports — export diagnostic sessions for inspection and sharing.
🎛️ Flexible visibility configuration — choose Debug, Profile, Release, Debug + Release, or All modes.
🔒 Opt-in monitoring — configure diagnostics according to your application's requirements.

💡 Metric availability varies by platform. CPU usage, network traffic, thermal state, and device details may be estimates, unavailable, or platform-dependent.

📦 Installation

Add the dependency to your pubspec.yaml:

dependencies:
  device_diagnostics: ^0.0.1

Then run:

flutter pub get

🚨 If you are installing a newer published version, replace 0.0.1 with the version listed on pub.dev.

🚀 Quick Start

Initialize diagnostics before calling runApp():

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

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

  await DeviceDiagnostics.initialize(
    config: const DiagnosticConfig(
      visibility: DiagnosticVisibility.debug,
    ),
  );

  runApp(
    DeviceDiagnostics.observability(
      child: MaterialApp(
        navigatorObservers: [
          DeviceDiagnostics.routeObserver,
        ],
        home: const MyHomePage(),
      ),
    ),
  );
}

🧩 What's happening here?

⚙️ DeviceDiagnostics.initialize() initializes the package configuration.
🎛️ DiagnosticConfig controls which build modes can display diagnostics and which metrics are enabled.
🧭 routeObserver tracks navigation events.
🖥️ DeviceDiagnostics.observability() wraps your app with the diagnostic UI when enabled for the current build mode.

🎛️ Visibility Modes Explained

Choose when the diagnostic interface should be visible.

Mode	🐛 Debug	🔬 Profile	🚀 Release
`debug`	✅ Visible	❌ Hidden	❌ Hidden
`profile`	❌ Hidden	✅ Visible	❌ Hidden
`release`	❌ Hidden	❌ Hidden	✅ Visible
`debugAndRelease`	✅ Visible	❌ Hidden	✅ Visible
`all`	✅ Visible	✅ Visible	✅ Visible

🐛 `DiagnosticVisibility.debug`

Best for everyday development and debugging.

const DiagnosticConfig(
  visibility: DiagnosticVisibility.debug,
)

🔬 `DiagnosticVisibility.profile`

Use this mode when profiling performance without enabling the diagnostic UI in ordinary Debug or Release builds.

const DiagnosticConfig(
  visibility: DiagnosticVisibility.profile,
)

🚀 `DiagnosticVisibility.release`

Enables diagnostic visibility in Release builds. Use it only when you intentionally want diagnostics available in production.

const DiagnosticConfig(
  visibility: DiagnosticVisibility.release,
)

🔄 `DiagnosticVisibility.debugAndRelease`

Enables diagnostic visibility in Debug and Release builds while hiding it in Profile builds.

const DiagnosticConfig(
  visibility: DiagnosticVisibility.debugAndRelease,
)

🌍 `DiagnosticVisibility.all`

Enables diagnostic visibility in all three build modes.

const DiagnosticConfig(
  visibility: DiagnosticVisibility.all,
)

⚠️ Important: Visibility configuration controls the diagnostic UI's build-mode visibility. It should not be treated as a security boundary or a substitute for access control, privacy safeguards, or production monitoring policies.

⚙️ Configuration Reference

Configure monitoring according to your application's needs.

const DiagnosticConfig(
  visibility: DiagnosticVisibility.debug,
  sampleInterval: Duration(seconds: 1),
  enableThermalMonitoring: true,
  enableCpuMonitoring: true,
  enableMemoryMonitoring: true,
  enableNetworkMonitoring: true,
  enableFrameMonitoring: true,
  showFloatingButtonWhenIdle: true,
)

Option	Description
🎛️ `visibility`	Selects the build modes in which the diagnostic UI is visible.
⏱️ `sampleInterval`	Controls how frequently diagnostic metrics are sampled.
🌡️ `enableThermalMonitoring`	Enables thermal-state monitoring where supported.
⚡ `enableCpuMonitoring`	Enables process CPU usage sampling where supported.
🧠 `enableMemoryMonitoring`	Enables memory usage sampling.
🌐 `enableNetworkMonitoring`	Controls network diagnostics when supported by the implementation.
🎬 `enableFrameMonitoring`	Enables frame performance monitoring.
🖲️ `showFloatingButtonWhenIdle`	Controls whether the floating diagnostic button is shown while a session is idle.

💡 The configured sampling interval must be at least 250 milliseconds if your configuration validation enforces that minimum.

🌐 HTTP Network Instrumentation

Use DiagnosticHttpClient to record HTTP body-byte metrics for requests made through the diagnostic client.

final client = DiagnosticHttpClient();

try {
  final response = await client.get(
    Uri.parse('https://example.com/api'),
  );

  debugPrint('Status code: ${response.statusCode}');
} finally {
  client.close();
}

📡 What can it track?

📤 Outgoing request body bytes.
📥 Incoming response body bytes.
🧭 Network activity associated with diagnostic routes, subject to the implementation's attribution behavior.

⚠️ These measurements are not necessarily total network usage. They may exclude headers, TLS overhead, retransmissions, and traffic sent through other HTTP clients or networking APIs.

📊 Diagnostic Sessions

Start a diagnostic session using the controller:

final controller = DeviceDiagnostics.controller;

await controller.start();

When you have finished collecting diagnostics, export the session report:

await controller.stopAndExportPdf(
  share: false,
);

🔁 Typical workflow

▶️ Start a diagnostic session.
📈 Reproduce the performance issue or user-reported bug.
🧭 Navigate through the relevant screens.
⏹️ Stop the session and generate the report.
📄 Inspect or share the PDF, depending on your configuration.

📄 PDF Diagnostic Reports

Generate a report to help investigate performance issues and reproduce bugs.

Depending on the data collected and platform support, reports can include:

📱 Device and operating-system information.
⚡ CPU and 🧠 memory measurements.
🎬 Frame-performance observations.
🌐 Recorded network byte metrics.
🧭 Screen visits and session timing.
📋 Diagnostic samples and summary information.

📝 Reports contain diagnostic data from the recorded session. Review the contents before sharing them, especially if they may reveal information about your application or its usage.

🧭 Route Tracking

Add the package's route observer to your MaterialApp:

MaterialApp(
  navigatorObservers: [
    DeviceDiagnostics.routeObserver,
  ],
  home: const MyHomePage(),
);

This allows the package to observe supported navigation events and associate diagnostic activity with routes.

💡 For the clearest route names, use named routes where appropriate. Route attribution may depend on how navigation is implemented.

📱 Platform Support

Platform support depends on the metric and the underlying operating-system APIs.

Metric	🤖 Android	🍎 iOS
Device information	✅ Supported fields	✅ Supported fields
Memory usage	✅ Where available	✅ Where available
Process CPU estimate	✅ Where available	✅ Where available
Network type	✅ Where available	✅ Where available
Network byte counters	✅ Where available	⚠️ May be unavailable
Thermal state	✅ On supported Android versions	✅ On supported iOS versions
Frame monitoring	📊 Flutter-side monitoring	📊 Flutter-side monitoring
PDF report generation	📄 Subject to package/platform support	📄 Subject to package/platform support

Legend: ✅ Available where implemented · ⚠️ Limited or unavailable · 📊 Collected by Flutter-side instrumentation

🏗️ Architecture Overview

The package is organized into layers:

🎛️ Configuration — controls visibility and metric options.
🧠 Diagnostic controller — manages session state, sampling, and collected data.
📱 Native integrations — retrieve platform-specific metrics through a method channel.
🌐 Network instrumentation — records HTTP traffic passing through the provided client.
🧭 Route observer — tracks supported navigation events.
🖥️ Diagnostic overlay — displays diagnostic controls and information.
📄 Report generator — produces PDF diagnostic reports.

🔒 Privacy and Performance Considerations

🔐 Enable diagnostics intentionally, especially in Release builds.
📋 Review diagnostic reports before sharing them.
🌐 Remember that only traffic passing through the instrumented client can be counted by that client.
⚙️ Choose a sampling interval suitable for your workload.
🧪 Validate performance and metric behavior on real devices.
🛡️ Do not use UI visibility settings as access control for sensitive diagnostic information.

🛠️ Troubleshooting

❓ The diagnostic overlay is not visible

✅ Verify that the selected DiagnosticVisibility matches the current build mode.
⚙️ Initialize the package before runApp().
🧩 Ensure your app is wrapped using DeviceDiagnostics.observability().
🔎 Confirm that the idle floating button setting matches your expectations.

❓ Some metrics are missing

📱 Support varies by platform and operating-system version.
🔐 Some native APIs require permissions or return unavailable values.
🌐 iOS network byte counters may not be available through the current implementation.
🧪 Test on a physical device when emulator results are incomplete.

❓ No network activity is recorded

🌐 Make requests through DiagnosticHttpClient.
🔎 Confirm that network monitoring is enabled.
⚠️ Traffic from unrelated clients and networking APIs may not be captured.

🧑‍💻 Development

Run the project's checks before submitting changes:

flutter pub get
flutter analyze
flutter test
flutter pub publish --dry-run

🗺️ Roadmap

Potential future improvements include:

📈 More diagnostic visualizations.
🧪 Expanded automated tests.
📱 Broader platform-specific metric support.
📄 Additional report customization.
🔍 More detailed performance insights.

🤝 Contributing

Contributions, bug reports, and feature suggestions are welcome!

🍴 Fork the repository.
🌿 Create a feature branch.
🛠️ Implement and test your changes.
📬 Submit a pull request with a clear description.

📬 Support

Found a bug or have a feature request?

📜 License

This package is distributed under the MIT License.

Made with ❤️ and Flutter by Rajat Das.

🔍 device_diagnostics

✨ Features

📦 Installation

🚀 Quick Start

🧩 What's happening here?

🎛️ Visibility Modes Explained

🐛 `DiagnosticVisibility.debug`

🔬 `DiagnosticVisibility.profile`

🚀 `DiagnosticVisibility.release`

🔄 `DiagnosticVisibility.debugAndRelease`

🌍 `DiagnosticVisibility.all`

⚙️ Configuration Reference

🌐 HTTP Network Instrumentation

📡 What can it track?

📊 Diagnostic Sessions

🔁 Typical workflow

📄 PDF Diagnostic Reports

🧭 Route Tracking

📱 Platform Support

🏗️ Architecture Overview

🔒 Privacy and Performance Considerations

🛠️ Troubleshooting

❓ The diagnostic overlay is not visible

❓ Some metrics are missing

❓ No network activity is recorded

🧑‍💻 Development

🗺️ Roadmap

🤝 Contributing

📬 Support

📜 License

Libraries

device_diagnostics package

🔍 device_diagnostics

✨ Features

📦 Installation

🚀 Quick Start

🧩 What's happening here?

🎛️ Visibility Modes Explained

🐛 DiagnosticVisibility.debug

🔬 DiagnosticVisibility.profile

🚀 DiagnosticVisibility.release

🔄 DiagnosticVisibility.debugAndRelease

🌍 DiagnosticVisibility.all

⚙️ Configuration Reference

🌐 HTTP Network Instrumentation

📡 What can it track?

📊 Diagnostic Sessions

🔁 Typical workflow

📄 PDF Diagnostic Reports

🧭 Route Tracking

📱 Platform Support

🏗️ Architecture Overview

🔒 Privacy and Performance Considerations

🛠️ Troubleshooting

❓ The diagnostic overlay is not visible

❓ Some metrics are missing

❓ No network activity is recorded

🧑‍💻 Development

🗺️ Roadmap

🤝 Contributing

📬 Support

📜 License

Libraries

device_diagnostics package

🐛 `DiagnosticVisibility.debug`

🔬 `DiagnosticVisibility.profile`

🚀 `DiagnosticVisibility.release`

🔄 `DiagnosticVisibility.debugAndRelease`

🌍 `DiagnosticVisibility.all`