
# Observation と起動の計測

Spring と同じように、アプリを計測するツールは二つあります。

- **`ApplicationStartup`** は起動を計測します。環境、コンテキスト、各 Bean の作成、そして起動中の独自のステップです。
- **`Observation`** は起動の後に動くものを計測します。メソッド、リクエスト、任意のコードの断片です。`@Observed` は、周りにコードを書かずにメソッドを計測します。

どちらも、計測したものをリスナーに送ります。デフォルトではリスナーがいないため、何かが聞くまでコストはかかりません。リスナーは、Flutter スターターのデバッグタイムライン、ログ、独自のハンドラーなどです。

## 使う理由

画面や起動が遅い原因は、推測できません。計測すれば、どの Bean の作成に 300 ms かかるか、どのメソッドが毎秒 40 回動くか、表示の前にアプリが何を待っているかがわかります。フレームワークは自分のステップをすでに計測しており、同じツールであなたのコードも計測でき、同じビューアーが両方を表示します。

## 独自の計測

計測するものに応じてツールを選びます。

```dart
// 1. Bean のメソッド: アノテーションだけで、周りにコードは不要。
@Service()
class Catalog {
  @Observed(name: 'catalog.load')
  Future<List<Book>> load() async { /* ... */ }
}

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

// または、タグ付きで自分で開始と停止をする。
final observation = observations.start('search.query')
  ..lowCardinalityKeyValue('language', 'ja');
try {
  /* ... */
} finally {
  observation.stop();
}

// 3. 起動の作業: ApplicationStartup のステップ。
final step = startup.start('app.cache.warm')..tag('entries', 120);
/* ... */
step.end();
```

`observations` は `ObservationRegistry` Bean、`startup` はコンテキストの `ApplicationStartup` です (Bean は `ConfigurableListableBeanFactory` から取得できます)。独自の `ApplicationEvent` には何も必要ありません。Flutter スターターは、コンテキストが発行するすべてのイベントを記録します。

## Observation

| クラス | 内容 |
|---|---|
| `ObservationRegistry` | Observation を作り、ハンドラーを保持する。`ObservationRegistry.noop`、またはハンドラーのないレジストリは、何もしない Observation を作る |
| `Observation` | 一つの計測: `start()`、`stop()`、`error(e)`、タグ、親。`observe(body)` はその中で `body` を実行し、`Future` も扱える。Future の完了で停止し、そのエラーを記録する |
| `ObservationHandler` | Observation の開始、失敗、停止を通知される。デバッグタイムラインもその一つ |
| `ObservationContext` | ハンドラーが受け取るもの: 名前、コンテキスト名、タグ、開始、所要時間、エラー、親 |

別の Observation が動いている間に開始した Observation は、その子になります。`await` をまたいでも同じです (現在の Observation は `Zone` に保持されます)。

```dart
final class SlowCalls extends ObservationHandler {
  @override
  void onStop(ObservationContext context) {
    if (context.duration! > const Duration(milliseconds: 100)) {
      log.warning('${context.contextualName} took ${context.duration}');
    }
  }
}
```

ハンドラーを Bean として宣言すると、Spring Boot がそれを `observationRegistry` Bean に渡します。

## @Observed

メソッドの `@Observed` は各呼び出しを計測し、クラスの `@Observed` はそのすべてのメソッド (getter と setter を除く) を計測します。メソッド自身のアノテーションがクラスのものより優先されます。

| パラメーター | デフォルト | 意味 |
|---|---|---|
| `name` | `method.observed` | Observation の名前 |
| `contextualName` | `Class#method` | 表示される名前 |
| `lowCardinalityKeyValues` | なし | key、value、key、value の形のタグ |

すべての Observation には、`class` と `method` のタグも付きます。

### ビルド時のオンとオフ

Spring Boot では、`@Observed` は次の設定のときだけ動作します。

```yaml
spring:
  observations:
    annotations:
      enabled: true
```

このプロパティは、実行だけでなくビルドを決めます。有効にすると、`@Observed` を有効にするモジュールがアプリに含まれ、ジェネレーターは `@Observed` を持つ Bean にだけプロキシを書き出し、他の Bean には書き出しません。無効だと、モジュールは除外され、`@Observed` に一致するものがなくなり、ジェネレーターはプロキシをまったく書き出しません。アノテーションは単なるメタデータで、コストはかかりません。Spring Boot (`management.observations.annotations.enabled`) と同じく、デフォルトではオフです。

### 仕組み

`@Observed` は AOP です。ビルド時に、ジェネレーターはアドバイザーが一致しうる Bean のプロキシクラスを書き出します。起動時に、Bean ポストプロセッサーの `AspectAutoProxyCreator` が、そのような各 Bean を、初期化が終わった後にそのプロキシに置き換えます。その後、マークされたメソッドの各呼び出しはプロキシを通ってアドバイスに届き、アドバイスがそれを Observation の中で実行します。

したがって、Spring と同じく次のようになります。

- コンストラクター、インジェクション、`@PostConstruct` は計測されません。プロキシが存在する前に動くためです。起動は `ApplicationStartup` が計測します。
- Bean の内部からの呼び出し (`this.load()`) は計測されません。プロキシを通らないためです。

`ObservedAspect` は `@Aspect` クラスとしてのアドバイスです。`ObservedPointcut` と `ObservedInterceptor` は、アドバイザー Bean 向けの同じアドバイスで、Spring Boot はこれを登録します。

## ApplicationStartup

フレームワークは起動の各部分の周りにステップを開始し、`BufferingApplicationStartup` がそれらを保持します。

| ステップ | 計測するもの |
|---|---|
| `spring.boot.application.starting` | `run` から環境が読み込まれるまで |
| `spring.boot.application.environment-prepared` | 環境の読み込み |
| `spring.boot.application.context` | コンテキストの作成とリフレッシュ、その中のすべての Bean |
| `spring.beans.instantiate` (タグ `beanName`) | 一つの Bean。コンストラクターからポストプロセッサーの終わりまで |

```dart
final startup = BufferingApplicationStartup();
SpringApplication([appBeans], applicationStartup: startup).run(args);
for (final step in startup.steps) {
  print(step); // spring.beans.instantiate beanName=catalog 12 ms
}
```

`record(name, startedAt:, duration:, tags:)` は、すでに実行されたステップを追加します。startup が存在する前に起きたことや、長さのないイベントです。

Flutter スターターは、自身の `ApplicationStartup` を常に設定します。スプラッシュのステージとアプリケーションイベントはすべてのアプリで記録され、各 Bean はデバッグタイムラインがあるときだけ記録されます。[タイムライン](../../spring-boot-starter-flutter/timeline.md) を参照してください。

## Spring (Java) との対応

| Spring | ここでは |
|---|---|
| `io.micrometer.observation.Observation`、`ObservationRegistry`、`ObservationHandler` | 同じ名前で、Micrometer なし |
| `@Observed`、`ObservedAspect` | 同じ |
| `management.observations.annotations.enabled` | `spring.observations.annotations.enabled`。プロキシを生成するかどうかも決める |
| `org.springframework.core.metrics.ApplicationStartup`、`BufferingApplicationStartup` | 同じ。加えて `record` |

## 関連項目

- [AOP](../aop/index.md)
- [タイムライン](../../spring-boot-starter-flutter/timeline.md)
- [BeanPostProcessor](../beans/bean-post-processor.md)
