The debug panel

The debug panel is a panel over the running app for whoever builds it. Each tab shows one side of the application: the logs, the frame meter, the configuration with the source of every value, the beans, the themes and the stages of the start. It opens with the action debug.open: ⌘⇧D (Ctrl+Shift+D elsewhere), or four quick taps and a fifth held three seconds, on every platform, phones included.

Why

On a phone or in a browser there is no console at hand, and the question is often "which value did this build get?" or "which profile is active?". The panel answers on the device itself, from the running context. And it costs nothing in what users run: by default the build leaves its code out of release builds.

Example

Nothing to write in a debug build: the panel is there, and ⌘⇧D opens it. To change how it opens, or to have it in every build:

# lib/resources/application.yml
spring:
  flutter:
    debug:
      enabled: true          # true: every build; false: none; not set: debug and profile builds
    shortcuts:
      debug.open: [primary+shift+d, taps:5+hold:2s]

The modules

The panel and each of its tools are separate modules of the build, each with its own property, so a release build can have one and not the others:

Module Property Bean Action and keys
The panel (springBootStarterFlutterDebugAutoConfiguration) spring.flutter.debug.enabled debugPanel debug.open: ⌘⇧D (Ctrl+Shift+D), or taps:4+hold:3s
The frame meter (springBootStarterFlutterDebugFrameMeterAutoConfiguration) spring.flutter.debug.frame-meter.enabled debugFrameMeter debug.frame-meter: ⌘⇧X (Ctrl+Shift+X), or taps:5+hold:2s (five quick taps and a sixth held two seconds)
The motion switch (springBootStarterFlutterDebugMotionAutoConfiguration) spring.flutter.debug.motion.enabled debugMotion debug.motion: ⌘⇧M (Ctrl+Shift+M)
The timeline (springBootStarterFlutterDebugTimelineAutoConfiguration) spring.flutter.debug.timeline.enabled debugTimeline debug.timeline: ⌘⇧L (Ctrl+Shift+L), or taps:6+hold:2s
Dragging the overlays (springBootStarterFlutterDebugDragAutoConfiguration) spring.flutter.debug.drag.enabled (not set: never) debugOverlayDrag none: drag an overlay

The keys of the tools are set like the panel's: spring.flutter.shortcuts.debug.frame-meter, spring.flutter.shortcuts.debug.motion, spring.flutter.shortcuts.debug.timeline.

The frame meter and the timeline show small widgets over the app; the dock of the debug overlays puts those of one corner together. While the panel is open they hide: their tabs show the same thing.

For example, a release build with only the frame meter and no panel:

spring:
  flutter:
    debug:
      enabled: false
      frame-meter:
        enabled: true
      motion:
        enabled: false
    frame-meter:
      position: bottom-right

The frame meter then starts in the corner spring.flutter.frame-meter.position, and the action debug.frame-meter shows it or hides it.

When a module is in the app

Each of these properties (spring.flutter.debug.enabled, spring.flutter.debug.frame-meter.enabled, spring.flutter.debug.motion.enabled, spring.flutter.debug.timeline.enabled, spring.flutter.debug.drag.enabled) is read by the generator when it writes main.spring.dart, so it decides what code the app contains:

Value The module
not set (the default) In debug and profile builds only. The module is written behind a release-mode condition, so a release build compiles it away
true In every build, release included
false In no build: the module is not written, and the app has none of its code

Set to false in a profile file, each also turns off its feature in a running app whose build has it. See Modules left out of the build for how a module's build condition works.

The tabs

Tab What it shows
Logs The records of the logging system's buffer (logBuffer), newest first and live, filtered by level and text
Frames The frame meter on or off over the app, and its corner, without a new build. It uses the debugFrameMeter bean; when the build left the frame meter out, the tab says it is not in this build
Motion Every animation of the app on, or off as the device's "reduce motion" turns it off (motion.enabled sets it for a build). It uses the debugMotion bean; when the build left the motion switch out, the tab says it is not in this build
Configuration The active profiles and every property with the source that sets it. Values of keys that name a secret (password, secret, token, key, credential) show as ******, as Spring Boot's actuator does
Beans Every bean of the context with its type
Theme The themes the app's own files declare or choose (SpringThemes.ownNames; not the base themes a source file brings) and system; a tap shows one
Start When each stage of the start was reached

A tab of your own

A tab is a DebugPanelSection bean, in the order of the beans (@Order, Ordered):

// The basket's content, for whoever tests the checkout.
@Component()
@Order(100)
class BasketSection implements DebugPanelSection {
  BasketSection(this.basket);

  final Basket basket;

  @override
  String get title => 'Basket';

  @override
  Widget build(BuildContext context) => Text('${basket.count} books');
}

DebugStyle.of(context), DebugChip and DebugFilter give a tab the panel's look. A tab of your own lives in your code, so keep it out of release builds yourself, for example with @Profile(['debug', 'profile']).

The panel's state

debugPanel (a DebugPanel, a ChangeNotifier) is the panel's state:

Member Meaning
isOpen Whether the panel shows
toggle() Opens the panel, or closes it
close() Closes it

It is also the KeyedShortcutHandler of debug.open, with the default keys primary+shift+d and taps:4+hold:3s. The panel is installed over the app by a FlutterAppCustomizer (debugPanelCustomizer).

The other two modules have a state bean each:

Bean Member Meaning
debugFrameMeter (DebugFrameMeter) on Whether the frame meter shows over the app (the Frames tab and debug.frame-meter set it)
position The corner of the frame meter
debugMotion (DebugMotion) animations Whether the animations of the app run (the Motion tab and debug.motion set it)

Each is the KeyedShortcutHandler of its action.

The property

Key Type Default Meaning
spring.flutter.debug.enabled true, false not set Read by the generator. true: the panel is in every build. false: in none (no code). Not set: debug and profile builds only
spring.flutter.debug.frame-meter.enabled true, false not set Read by the generator. The same, for the frame meter module
spring.flutter.debug.motion.enabled true, false not set Read by the generator. The same, for the motion switch module
spring.flutter.shortcuts.debug.open keys or taps [primary+shift+d, taps:4+hold:3s] What opens the panel (see Keyboard shortcuts and taps)
spring.flutter.shortcuts.debug.frame-meter keys or taps [primary+shift+x, taps:5+hold:2s] What shows or hides the frame meter
spring.flutter.shortcuts.debug.motion keys or taps primary+shift+m What turns the animations on or off
spring.flutter.frame-meter.position corner top-right The corner the frame meter starts in

In Spring (Java)

Spring Boot's actuator shows the same facts (/actuator/env, /actuator/beans, /actuator/loggers) over HTTP for a server. The panel shows them on the device, in the app itself.

See also