The timeline

The timeline shows where the time goes: the stages of the splash, each bean's creation, the application events, and every observation after the start (@Observed methods, your own measurements). A pill over the app sums it up; a tap opens the full view.

Why

"The app takes four seconds to show" is not something you can fix. "The splash waits 1.8 s for its minimum while the context is ready at 0.4 s" or "themeSourceLoader takes 300 ms" is. The framework measures its own start with ApplicationStartup and anything after with Observation; the timeline puts both on one time axis, in the running app, on any device.

Example

spring:
  flutter:
    debug:
      timeline:
        enabled: true          # in every build; not set: debug and profile only
        position: bottom-right

Run the app and press ⌘⇧L (Ctrl+Shift+L), or on a phone tap six times quickly and hold the seventh. The pill shows in its corner:

⏱ start 438ms · app 3.9s
catalog.load 84ms ▁▂▅▇▂

start is when the context was ready, app when the splash was gone, both from the moment the page opened. The second line is the last observation.

The full view

Tap the pill. On a wide screen the view is a panel on the right; on a phone it covers the screen. It has three tabs:

Copy JSON puts everything on the clipboard: the steps, the events and the observation statistics, for a bug report.

The pill lives in the dock of the debug overlays, with the frame meter; the full view covers them while it is open. The debug panel has the same view in its Timeline tab.

What it measures

Row Where it comes from Recorded
Splash stages (page … app) The SplashStages, a step spring.flutter.splash.<stage> each Always
Application events Every event the context publishes, a step spring.event (tag type) Always
Each bean (spring.beans.instantiate) The bean factory, from the constructor to the end of the post-processors With the timeline in the build, or spring.flutter.splash.trace
Observations Every Observation of the observationRegistry, @Observed methods included With the timeline in the build

The stages and the events cost almost nothing, so every app records them: the splashTrace bean (a BufferingApplicationStartup) has them, for a log, a test or your own screen. Each bean is a step only when something shows them, as there are hundreds.

Measuring your own code

// A method: no code around it (with spring.observations.annotations.enabled).
@Observed(name: 'catalog.load')
Future<List<Book>> load() async { /* ... */ }

// A piece of code.
final books = await observations.observe('catalog.load', () => api.books());

// A step of the start.
final step = startup.start('app.cache.warm');
/* ... */
step.end();

Each shows in the timeline: an observation in the Observations tab and the pill, a step of the start as a row of the Start tab. See Observations and the start.

In the build or not

Like the other debug features, the timeline is a module of its own, decided by spring.flutter.debug.timeline.enabled:

Value The app
true Has it in every build, a release too
false Has no code of it
not set Has it in debug and profile builds; a release compiles it away

Without it, nothing measures each bean and nothing collects the observations; the stages and the events are still in the splashTrace bean.

The properties

Key Type Default Meaning
spring.flutter.debug.timeline.enabled bool not set Whether the build has the timeline (see above)
spring.flutter.debug.timeline.position corner bottom-left The corner of its pill
spring.flutter.splash.trace bool false Measures each bean without the timeline and logs the start once the splash is gone

The action is debug.timeline; change its keys with spring.flutter.shortcuts.debug.timeline (see Keyboard shortcuts and taps).

See also