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:
- Start: the stages of the splash as a coloured band, the events as dots, then each step of the start as a row: the beans grouped (the slowest first, ten shown, the rest one tap away). Zoom with − / + / Fit, a pinch or Ctrl+wheel.
- Observations: per name, how many, the average, the longest and the last; tap a row for a chart of its last calls. It updates live.
- Events: each application event the context published, with its time and type.
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).