flutter_telescope 1.3.0

A powerful Flutter package for network activity monitoring and debugging with beautiful UI and comprehensive logging.

🎬 Demo

flutter_telescope

A powerful Flutter package for network activity monitoring and debugging. Telescope provides comprehensive network request logging, beautiful UI for viewing network activities, and powerful debugging tools for Flutter applications.

Features

• 🌐 Network Activity Monitoring - Automatically logs all HTTP/Dio requests and responses
• 🎨 Beautiful UI - Modern, theme-aware interface for viewing network activities
• 📊 Detailed Information - Request/response headers, bodies, status codes, timing
• 🐛 Error Tracking - Comprehensive error logging and debugging information
• 📋 Copy & Share - Easy copying and sharing of network data
• 🔍 Floating Test Button - Quick access to network inspector
• 🌓 Theme Support - Light and dark mode compatibility
• 📝 JSON Formatting - Pretty-printed request/response bodies

Installation

Add this to your package's pubspec.yaml file:

dependencies:
  flutter_telescope: ^1.0.0

Then run:

flutter pub get

Quick Start

1. Initialize the Package

import 'package:flutter_telescope/flutter_telescope.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  NetworkInspector.initialize();
  runApp(MyApp());
}

2. Setup Dio Client (Recommended)

import 'package:flutter_telescope/flutter_telescope.dart';
import 'package:dio/dio.dart';

class MyService {
  late Dio _dioClient;
  
  MyService() {
    _dioClient = DioClientHelper.createDioWithInterceptor(
      logIsAllowed: true,
      isConsoleLogAllowed: true,
      baseUrl: 'https://api.example.com',
      onHttpFinish: (hashCode, title, message) {
        // Handle HTTP completion callbacks
        print('$title: $message');
      },
      headers: {
        'Content-Type': 'application/json',
        'Accept': 'application/json',
      },
    );
  }
  
  Future<void> fetchData() async {
    final response = await _dioClient.get('/users');
    return response.data;
  }
}

// Or just add the interceptor to an existing Dio instance
void addTelescopeToDio(Dio dio) {
  dio.interceptors.add(DioInterceptor());
}

// Setup Chopper Integration
// Chopper uses http.Client under the hood, so you can use TelescopeHttpClient!
import 'package:chopper/chopper.dart';

ChopperClient createChopperClient() {
  final telescopeClient = TelescopeHttpClient();
  return ChopperClient(
    baseUrl: Uri.parse('https://api.example.com'),
    client: telescopeClient, // Pass TelescopeHttpClient as the underlying client!
    converter: const JsonConverter(),
  );
}

// Retrofit Integration
// Retrofit (both Dio-based, so you can just add DioInterceptor!
import 'package:retrofit/retrofit.dart';

@RestApi(baseUrl: 'https://api.example.com')
abstract class ApiService {
  factory ApiService(Dio dio) = _ApiService;

  @GET('/users')
  Future<List<User>> getUsers();
}

// When creating your ApiService:
final dio = Dio();
dio.interceptors.add(DioInterceptor());
final apiService = ApiService(dio);

3. Setup HTTP Client

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

class MyHttpService {
  late HttpInterceptor _httpClient;
  
  MyHttpService() {
    _httpClient = HttpClientHelper.createHttpClient(
      logIsAllowed: true,
      isConsoleLogAllowed: true,
      baseUrl: Uri.parse('https://api.example.com'),
      headers: {
        'Content-Type': 'application/json',
      },
    );
  }
  
  Future<void> fetchData() async {
    final response = await _httpClient.get('/users');
    return response.body;
  }
}

// Or use TelescopeHttpClient as a drop-in replacement for http.Client
void useTelescopeHttpClient() {
  final client = TelescopeHttpClient();
  // Use client.get/post/etc. just like http.Client
}

4. Enable Floating Test Button

import 'package:flutter_telescope/flutter_telescope.dart';

void main() {
  WidgetsFlutterBinding.ensureInitialized();
  NetworkInspector.initialize();
  
  // Enable floating test button
  NetworkInspectorConfig.enableTestButton(
    alignment: Alignment.bottomRight,
    margin: 20.0,
    customButton: const Icon(Icons.network_check),
  );
  
  runApp(MyApp());
}

5. View Network Activities

import 'package:flutter_telescope/flutter_telescope.dart';

// Navigate to activity list
Navigator.push(
  context,
  MaterialPageRoute(builder: (context) => const ActivityPage()),
);

// Or use overlay for quick access
MaterialApp(
  home: NetworkInspectorOverlay(
    child: MyHomePage(),
  ),
)

API Reference

NetworkInspector

Main class for managing network monitoring.

Methods

• initialize() - Initialize the network inspector
• logActivity({...}) - Manually log network activity
• getActivities() - Get all logged activities
• clearActivities() - Clear all activities
• debugDatabase() - Print database debug information

NetworkInspectorConfig

Configuration for the floating test button.

Methods

• enableTestButton({...}) - Enable floating test button
• disableTestButton() - Disable floating test button
• isTestButtonEnabled - Check if test button is enabled

DioClientHelper

Helper for creating Dio clients with network monitoring.

Methods

• createDioWithInterceptor({...}) - Create Dio client with interceptor

HttpClientHelper

Helper for creating HTTP clients with network monitoring.

Methods

• createHttpClient({...}) - Create HTTP client with interceptor

Example App

See the example/ directory for a complete working example app that demonstrates all features of flutter_telescope.

Dependencies

• flutter: Flutter framework
• dio: ^5.9.0: HTTP client with interceptors
• http: ^1.6.0: HTTP client
• logger: ^2.4.0: Logging framework
• path: ^1.9.0: Path manipulation
• sqflite: ^2.3.3: Local database storage

Requirements

• Flutter SDK: ^3.10.7
• Dart SDK: ^3.10.7

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

If you have any questions or need help, please:

• Open an issue on GitHub
• Check the example app for usage patterns
• Read the API documentation above

FAQ

Q: Does flutter_telescope work in release mode?

A: No, by default it's disabled in release builds for security and performance. You can enable it with NetworkInspectorConfig.setCaptureInReleaseMode(true), but we strongly recommend not doing so for production apps.

Q: How do I redact sensitive data in logs?

A: Sensitive headers (Authorization, Cookie, Set-Cookie, X-Api-Key, Api-Key, X-Auth-Token) are redacted by default. You can customize this with:

// Configure redaction
NetworkInspectorConfig.configureRedaction(
  enabled: true, // default
  placeholder: "***REDACTED***",
  sensitiveHeaders: {"Authorization", "X-My-Secret-Header"},
);
// Add a single sensitive header
NetworkInspectorConfig.addSensitiveHeader("X-My-Token");
// Remove a sensitive header
NetworkInspectorConfig.removeSensitiveHeader("Cookie");

Q: How do I prevent the database from growing too large?

A: flutter_telescope has two mechanisms for this:

1. Automatic time-based cleanup (default: 10 minutes, enabled by default):

   NetworkInspectorConfig.configureAutoCleanup(
     enabled: true,
     interval: Duration(minutes: 30),
   );
   

2. Max row cap (default: 1000 rows):

   NetworkInspectorConfig.setMaxStoredActivities(2000);
   

   You can also manually clear all logs with NetworkInspector.clearActivities().

Q: Does it support streaming responses?

A: Yes! The TelescopeHttpClient (which extends http.BaseClient) fully supports streamed responses, along with multipart requests and all HTTP methods.

Q: How do I open the inspector without the floating button?

A: You can push the ActivityPage to your navigator:

Navigator.push(
  context,
  MaterialPageRoute(builder: (context) => const ActivityPage()),
);

Or if you're using NavigationService:

NavigationService.navigatorKey.currentState?.push(
  MaterialPageRoute(builder: (context) => const ActivityPage()),
);

Troubleshooting

Issue: The floating button doesn't work

• Fix 1: Make sure you're using NetworkInspectorOverlay in your widget tree:

  MaterialApp(
    home: NetworkInspectorOverlay(child: MyHomePage()),
  )
  

• Fix 2: Make sure you enabled the button with NetworkInspectorConfig.enableTestButton()
• Fix 3: If you didn't set up NavigationService.navigatorKey, make sure there is a Navigator in the widget tree when the button is pressed

Issue: Some logs are missing

• Fix: If you're making requests in quick succession, you can ensure all logs are flushed with await NetworkInspector.flush() before calling getActivities().

Changelog

See CHANGELOG.md for a list of changes and version history.