
# タイムライン

タイムラインは、時間がどこで使われているかを表示します。スプラッシュのステージ、各 Bean の作成、アプリケーションイベント、そして起動後のすべての Observation (`@Observed` メソッド、独自の計測) です。アプリの上のピルが要約を示し、タップするとフルビューが開きます。

## 使う理由

「アプリの表示に 4 秒かかる」では、直せません。「コンテキストは 0.4 秒で準備できているのに、スプラッシュが最小時間の 1.8 秒を待っている」や「`themeSourceLoader` に 300 ms かかる」なら直せます。フレームワークは自身の起動を `ApplicationStartup` で、その後のものを `Observation` で計測します。タイムラインは、その両方を一つの時間軸に、実行中のアプリの上で、どのデバイスでも表示します。

## 例

```yaml
spring:
  flutter:
    debug:
      timeline:
        enabled: true          # すべてのビルド。未設定: デバッグとプロファイルのみ
        position: bottom-right
```

アプリを実行して ⌘⇧L (Ctrl+Shift+L) を押すか、スマートフォンでは素早く 6 回タップして 7 回目を押し続けます。ピルがその隅に表示されます。

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

`start` はコンテキストの準備ができた時刻、`app` はスプラッシュが消えた時刻で、どちらもページが開いた時点からの時間です。2 行目は直近の Observation です。

## フルビュー

ピルをタップします。広い画面ではビューは右側のパネルになり、スマートフォンでは画面全体を覆います。三つのタブがあります。

- **Start**: スプラッシュのステージを色付きの帯として、イベントをドットとして表示し、続いて起動の各ステップを行として表示します。Bean はグループ化され (遅いものが先で、10 件を表示し、残りはタップ一回)、ズームは − / + / Fit、ピンチ、Ctrl+ホイールで行います。
- **Observations**: 名前ごとに、回数、平均、最長、直近を表示します。行をタップすると直近の呼び出しのチャートが表示されます。ライブで更新されます。
- **Events**: コンテキストが発行した各アプリケーションイベントを、その時刻と型とともに表示します。

**Copy JSON** は、ステップ、イベント、Observation の統計のすべてをクリップボードに入れます。バグ報告のためです。

ピルは、フレームメーターとともに [デバッグオーバーレイのドック](overlays.md) の中にあります。フルビューは開いている間、それらを覆います。[デバッグパネル](debug-panel.md) は、その Timeline タブに同じビューを持ちます。

## 計測するもの

| 行 | 出どころ | 記録 |
|---|---|---|
| スプラッシュのステージ (`page` … `app`) | `SplashStages`。それぞれ `spring.flutter.splash.<stage>` のステップ | 常に |
| アプリケーションイベント | コンテキストが発行するすべてのイベント。ステップ `spring.event` (タグ `type`) | 常に |
| 各 Bean (`spring.beans.instantiate`) | Bean ファクトリー。コンストラクターからポストプロセッサーの終わりまで | ビルドにタイムラインがあるとき、または `spring.flutter.splash.trace` |
| Observation | `observationRegistry` のすべての `Observation`。`@Observed` メソッドを含む | ビルドにタイムラインがあるとき |

ステージとイベントはほとんどコストがかからないため、すべてのアプリが記録します。`splashTrace` Bean (`BufferingApplicationStartup`) がそれらを持ち、ログ、テスト、独自の画面に使えます。各 Bean は数百あるため、何かがそれらを表示するときだけステップになります。

## 独自のコードの計測

```dart
// メソッド: 周りにコードは不要 (spring.observations.annotations.enabled が必要)。
@Observed(name: 'catalog.load')
Future<List<Book>> load() async { /* ... */ }

// コードの断片。
final books = await observations.observe('catalog.load', () => api.books());

// 起動のステップ。
final step = startup.start('app.cache.warm');
/* ... */
step.end();
```

どれもタイムラインに表示されます。Observation は Observations タブとピルに、起動のステップは Start タブの行として表示されます。[Observation と起動の計測](../spring-core-dart/observations/index.md) を参照してください。

## ビルドに含めるかどうか

他のデバッグ機能と同じく、タイムラインは独自のモジュールで、`spring.flutter.debug.timeline.enabled` で決まります。

| 値 | アプリ |
|---|---|
| `true` | すべてのビルドに含まれる。リリースも含む |
| `false` | そのコードを一切持たない |
| 未設定 | デバッグとプロファイルのビルドに含まれる。リリースではコンパイル時に取り除かれる |

含まれていなければ、各 Bean を計測するものも、Observation を集めるものもありません。ステージとイベントは、それでも `splashTrace` Bean にあります。

## プロパティ

| キー | 型 | デフォルト | 意味 |
|---|---|---|---|
| `spring.flutter.debug.timeline.enabled` | bool | 未設定 | ビルドにタイムラインを含めるかどうか (上を参照) |
| `spring.flutter.debug.timeline.position` | 隅 | `bottom-left` | そのピルの隅 |
| `spring.flutter.splash.trace` | bool | `false` | タイムラインなしで各 Bean を計測し、スプラッシュが消えたら起動をログに出す |

アクションは `debug.timeline` で、キーは `spring.flutter.shortcuts.debug.timeline` で変更します ([キーボードショートカットとタップ](shortcuts.md) を参照)。

## 関連項目

- [Observation と起動の計測](../spring-core-dart/observations/index.md)
- [デバッグオーバーレイ](overlays.md)
- [フレームメーター](frame-meter.md)
- [スプラッシュと起動](splash.md)
