flutter
/

BLoC DevTools: Debugging, Logging & Performance Profiling

Last Sync: Today

On this page

11
0%
5 min read
Remaining
5 minleft

Click any section to jump — progress syncs automatically

flutter

BLoC DevTools: Debugging, Logging & Performance Profiling

Introduction

Debugging state management is a critical part of building robust Flutter apps. BLoC provides powerful tools to inspect, log, and profile your state changes and event flows. This guide covers how to leverage Flutter DevTools with BLoC, use BlocObserver for global logging, and adopt best practices to identify performance bottlenecks, memory leaks, and unexpected behavior.

Why DevTools Matter for BLoC

  • Event Visibility – See exactly what events are dispatched and in what order.
  • State Transitions – Monitor how states evolve over time.
  • Performance Insights – Identify expensive event handlers or unnecessary rebuilds.
  • Memory Leak Detection – Ensure BLoCs and Cubits are disposed correctly.
  • Debugging Confidence – Understand the flow of data without adding print statements everywhere.

Setting Up BlocObserver

BlocObserver is the central entry point for all BLoC and Cubit events, transitions, and errors. By creating a custom observer, you can log everything to the console, send data to a debugging service, or even visualize it in DevTools.

DARTRead-only
1
import 'package:flutter_bloc/flutter_bloc.dart';

class SimpleBlocObserver extends BlocObserver {
  @override
  void onEvent(Bloc bloc, Object? event) {
    print('${bloc.runtimeType} event: $event');
    super.onEvent(bloc, event);
  }

  @override
  void onTransition(Bloc bloc, Transition transition) {
    print('${bloc.runtimeType} transition: $transition');
    super.onTransition(bloc, transition);
  }

  @override
  void onError(BlocBase bloc, Object error, StackTrace stackTrace) {
    print('${bloc.runtimeType} error: $error');
    super.onError(bloc, error, stackTrace);
  }
}

void main() {
  Bloc.observer = SimpleBlocObserver();
  runApp(MyApp());
}

For more advanced logging, you can integrate with logging packages like logger or dart:developer to send events to Flutter DevTools.

Using Flutter DevTools with BLoC

Flutter DevTools provides a timeline, logging, and performance profiling. To see BLoC events in DevTools, you need to log them using dart:developer's log method, which appears in the Logging tab.

DARTRead-only
1
import 'dart:developer' as developer;

class DevToolsBlocObserver extends BlocObserver {
  @override
  void onEvent(Bloc bloc, Object? event) {
    developer.log('$event', name: '${bloc.runtimeType}.event');
    super.onEvent(bloc, event);
  }

  @override
  void onTransition(Bloc bloc, Transition transition) {
    developer.log(
      '${transition.currentState} -> ${transition.nextState}',
      name: '${bloc.runtimeType}.transition',
    );
    super.onTransition(bloc, transition);
  }
}

Now run your app with flutter run and open DevTools. In the Logging tab, you can filter by your name parameter to see all BLoC events and transitions in real time.

Advanced Debugging with BlocObserver

You can add more sophisticated instrumentation, such as measuring the time taken by each event or tracking memory usage.

DARTRead-only
1
class TimedBlocObserver extends BlocObserver {
  final Stopwatch _stopwatch = Stopwatch();

  @override
  void onEvent(Bloc bloc, Object? event) {
    _stopwatch.reset();
    _stopwatch.start();
    super.onEvent(bloc, event);
  }

  @override
  void onTransition(Bloc bloc, Transition transition) {
    _stopwatch.stop();
    print('${bloc.runtimeType} processed ${transition.event} in ${_stopwatch.elapsedMilliseconds}ms');
    super.onTransition(bloc, transition);
  }
}

Profiling Performance

Flutter DevTools provides a Performance tab where you can record a timeline of your app’s activity. Use the BlocObserver to add timeline events so that BLoC operations appear in the timeline.

DARTRead-only
1
import 'dart:developer' as developer;

class PerformanceBlocObserver extends BlocObserver {
  @override
  void onEvent(Bloc bloc, Object? event) {
    developer.Timeline.startSync('${bloc.runtimeType}.$event');
    super.onEvent(bloc, event);
  }

  @override
  void onTransition(Bloc bloc, Transition transition) {
    developer.Timeline.finishSync();
    super.onTransition(bloc, transition);
  }
}

Now in DevTools, go to Performance, record, and you’ll see BLoC events as asynchronous timeline segments, making it easy to spot long-running handlers.

Debugging State Rebuilds

Use DevTools’ Widget Inspector to see which widgets rebuild. Combine with buildWhen debugging by adding logs inside your BlocBuilder’s buildWhen to see why rebuilds happen.

DARTRead-only
1
BlocBuilder<MyBloc, MyState>(
  buildWhen: (previous, current) {
    final shouldRebuild = previous.value != current.value;
    print('Rebuild? $shouldRebuild (${previous.value} vs ${current.value})');
    return shouldRebuild;
  },
  builder: (context, state) => Text('${state.value}'),
);

Memory Leak Detection

BLoC controllers should be disposed when no longer needed. Use BlocObserver to track when BLoCs are created and closed, ensuring they aren’t lingering.

DARTRead-only
1
class MemoryLeakObserver extends BlocObserver {
  final _activeBlocs = <BlocBase>[];

  @override
  void onCreate(BlocBase bloc) {
    _activeBlocs.add(bloc);
    print('${bloc.runtimeType} created, active: ${_activeBlocs.length}');
    super.onCreate(bloc);
  }

  @override
  void onClose(BlocBase bloc) {
    _activeBlocs.remove(bloc);
    print('${bloc.runtimeType} closed, active: ${_activeBlocs.length}');
    super.onClose(bloc);
  }
}

Best Practices

  • Use a custom BlocObserver – Centralize logging and debugging.
  • Log only in debug mode – Avoid logging in production to reduce overhead. 
    if (kDebugMode) Bloc.observer = DebugBlocObserver();
  • Use dart:developer for DevTools integration – Gain timeline and logging insights.
  • Name your events and states clearly – Good names make logs understandable.
  • Add buildWhen logging when debugging rebuilds – Understand why your UI rebuilds.
  • Monitor active BLoCs – Ensure they are closed properly.
  • Profile with DevTools regularly – Catch performance regressions early.

Common Mistakes

  • ❌ Leaving debug logs in production – Can bloat app and expose internal details. ✅ Wrap logging in kDebugMode or use a configurable logger.
  • ❌ Not disposing BLoCs – Causes memory leaks and stale events. ✅ Use BlocProvider and ensure close is called when the widget is removed.
  • ❌ Over-logging – Excessive console output can hide important info. ✅ Log only essential events or use filtering.
  • ❌ Ignoring DevTools warnings – Many issues appear as warnings in DevTools; investigate them.
  • ❌ Not testing BlocObserver – Observers are code; test them too.

Conclusion

BLoC DevTools, combined with a custom BlocObserver, provides deep insight into your app’s state management. By integrating with Flutter DevTools, you can monitor events, profile performance, and detect memory leaks. Adopting these practices will make your development process faster and your apps more reliable.

Try it yourself

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

// Simple BlocObserver to log to console
class ConsoleBlocObserver extends BlocObserver {
  @override
  void onEvent(Bloc bloc, Object? event) {
    print('EVENT: ${bloc.runtimeType} -> $event');
    super.onEvent(bloc, event);
  }

  @override
  void onTransition(Bloc bloc, Transition transition) {
    print('TRANSITION: ${bloc.runtimeType} -> ${transition.currentState} -> ${transition.nextState}');
    super.onTransition(bloc, transition);
  }

  @override
  void onError(BlocBase bloc, Object error, StackTrace stackTrace) {
    print('ERROR: ${bloc.runtimeType} -> $error');
    super.onError(bloc, error, stackTrace);
  }
}

void main() {
  Bloc.observer = ConsoleBlocObserver();
  runApp(MyApp());
}

class CounterCubit extends Cubit<int> {
  CounterCubit() : super(0);
  void increment() => emit(state + 1);
  void decrement() => emit(state - 1);
}

class MyApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: BlocProvider(
        create: (_) => CounterCubit(),
        child: CounterPage(),
      ),
    );
  }
}

class CounterPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final cubit = context.watch<CounterCubit>();
    return Scaffold(
      appBar: AppBar(title: Text('BLoC DevTools Demo')),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            Text('Counter:', style: TextStyle(fontSize: 20)),
            Text('${cubit.state}', style: TextStyle(fontSize: 40)),
            SizedBox(height: 20),
            Row(
              mainAxisAlignment: MainAxisAlignment.center,
              children: [
                ElevatedButton(
                  onPressed: cubit.increment,
                  child: Icon(Icons.add),
                ),
                SizedBox(width: 20),
                ElevatedButton(
                  onPressed: cubit.decrement,
                  child: Icon(Icons.remove),
                ),
              ],
            ),
            SizedBox(height: 20),
            Text('Check console for logged events and transitions!'),
          ],
        ),
      ),
    );
  }
}

Test Your Knowledge

Q1
of 3

What class should you extend to globally observe BLoC events and transitions?

A
BlocObserver
B
BlocListener
C
BlocProvider
D
BlocBuilder
Q2
of 3

How do you log events to Flutter DevTools' Logging tab?

A
Using print statements
B
Using debugPrint
C
Using developer.log
D
Using BlocObserver.onEvent only
Q3
of 3

What is the purpose of onClose in a BLoC?

A
To log when the BLoC is created
B
To cancel subscriptions and release resources
C
To handle errors
D
To emit final states

Frequently Asked Questions

How do I see BLoC events in Flutter DevTools?

Use dart:developer's log function inside a custom BlocObserver and then view the Logging tab in DevTools. You can filter by the name parameter you pass.

Can I use BlocObserver with Cubit?

Yes, BlocObserver works for both Bloc and Cubit. It observes events (for Bloc), transitions, and errors for both.

How do I avoid logging in production?

Conditionally set the observer only in debug mode: if (kDebugMode) Bloc.observer = MyObserver();. Also guard individual log statements with if (kDebugMode).

What is the difference between `onEvent` and `onTransition`?

onEvent is called as soon as an event is added. onTransition is called when the state changes (i.e., after the event handler has emitted a new state).

How do I profile BLoC performance?

Use the dart:developer timeline APIs inside BlocObserver to mark event processing. Then record a timeline in DevTools Performance tab to see durations.

Previous

bloc logging

Next

bloc flutter web

Related Content

Need help?

Explore our comprehensive docs or start a chat with our tech experts.