Observation と起動の計測

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

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

使う理由

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

独自の計測

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

// 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 に保持されます)。

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 は次の設定のときだけ動作します。

spring:
  observations:
    annotations:
      enabled: true

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

仕組み

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

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

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。コンストラクターからポストプロセッサーの終わりまで
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 (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

関連項目