
# 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

```yaml
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](overlays.md), with the frame meter; the full view covers them while it is open. The [debug panel](debug-panel.md) 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

```dart
// 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](../spring-core-dart/observations/index.md).

## 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](shortcuts.md)).

## See also

- [Observations and the start](../spring-core-dart/observations/index.md)
- [Debug overlays](overlays.md)
- [The frame meter](frame-meter.md)
- [The splash and the start](splash.md)
