
# isolate の負荷

`IsolateLoads` は一つの質問に答えます: アプリケーションにはどの isolate があり、それぞれがどのくらい忙しいか。isolate ごと、または Flutter エンジンのスレッドごとに一つの行を返します。行には、イベントループがどのくらい遅れているか、働いている時間の割合、そして何を処理しているかが入ります。Spring Boot では Bean `isolateLoads` です。

これを読むものは二つあります。[Flutter アプリのタスクマネージャー](../../spring-boot-starter-flutter/isolates.md) と、Actuator の [`isolates` エンドポイント](../../spring-boot-actuator/isolates.md) です。独自のコードからも読めます。同じ計測値が、[Web サーバーの isolate のスケーリング](../../spring-boot-starter-web/server/scaling.md) を決めます。

## 使う理由

「サーバーが遅い」には、大きく異なる二つの原因があります。isolate が計算していて次のリクエストを受け取れないか、データベースを待っていて空いているかです。前者は isolate を増やせば直り、後者は直りません。行を見れば、どちらかがわかります。忙しい isolate は遅れ、待っている isolate は遅れません。

コンパイルされた Dart プログラムは、自分の isolate を列挙できず、isolate がどのくらいプロセッサー時間を使っているかを問い合わせることもできません。そのためフレームワークは、内側から計測できるものを計測します。このページでは、それで足りない部分も説明します。

## 例

```dart
import 'dart:isolate';

import 'package:spring_boot_dart/spring_boot_dart.dart';

@Service()
class Diagnostics {
  Diagnostics(this.loads);
  final IsolateLoads loads;

  // 行ごとに一行: "main (main): busy 0.02, lag 0:00:00.000180"。
  List<String> rows() => [
    for (final load in loads.all())
      '${load.name} (${load.kind}): busy ${load.busy}, lag ${load.lag}',
  ];

  // アプリケーションが自分で起動する isolate は、動いている間、一つの行になる。
  Future<Report> build() => loads.track('report', Isolate.run(buildReport));
}
```

最初の `all()` は計測を開始するもので、まだ遅れの値がありません。少し後にもう一度読んでください。

## 行

行は `IsolateLoad` です。`name` と `kind` 以外のすべての値は、ソースが計測できないとき `null` です。

| フィールド | JSON での名前 | 意味 |
|---|---|---|
| `name` | `name` | ログに表示される名前: `main`、`isolate-2`、`task-1`、`raster` |
| `kind` | `kind` | それが何か。下を参照 |
| `busy` | `busy` | 働いていた時間の割合。`0` から `1` |
| `lag` | `lagMicros` | イベントループがタイマーを実行するのがどのくらい遅れたかの平均: isolate が空いているときはゼロに近く、空いていないときは、ブロックしているものの長さ |
| `maxLag` | `maxLagMicros` | 計測された最長の遅れ |
| `active` | `active` | 今処理しているもの: 実行中のリクエスト、実行中のタスク |
| `memory` | `memory` | バイト単位のメモリー。isolate はプロセスのメモリーを共有するため、`main` の行だけが持つ: プロセスの常駐サイズ |
| `details` | `details` | 一つのソースだけが計測するものを、名前ごとに: `requests`、`queued`、`tasks`。時間の長さはマイクロ秒単位で、`Micros` で終わる名前になる |

`toJson()` と `IsolateLoad.fromJson` は JSON での名前を使います。行はこの形で isolate から別の isolate へ渡り、Actuator もこの形で応答します。`null` の値は省かれます。

| `kind` | 行の内容 |
|---|---|
| `main` | アプリケーションの最初の isolate |
| `server` | Web サーバーのプールの isolate |
| `task` | タスクエグゼキューターの isolate |
| `engine` | Flutter エンジンのスレッド |
| `tracked` | `track` で表示される作業 |
| ほかの語 | 独自のソース |

## ソース

`IsolateLoads` 自身は何も計測しません。すべての `IsolateLoadSource` Bean に、順番に問い合わせます。

| Bean | パッケージ | 行 |
|---|---|---|
| `isolateLoadSampler` | `spring_boot_dart` | 自分が動いている isolate: `lag`、`maxLag`、`busy`、そして最初の isolate では `memory` |
| `isolateTaskExecutor` | `spring_boot_dart` | 今存在する [タスクエグゼキューター](task-executor.md) の isolate ごとに一つ |
| `webServerLoadSource` | `spring_boot_starter_web` | その isolate 自身の行に追加する: `active` (実行中のリクエスト) と、詳細の `requests` (受け取ったすべてのリクエスト) および `refused` (サーバーがいっぱいで 503 を返したもの) |
| `serverIsolatePool` | `spring_boot_starter_web` | [サーバーのプール](../../spring-boot-starter-web/server/isolates.md) のほかの isolate の行。それぞれが最後に送ってきたもの |
| `flutterEngineLoads` | `spring_boot_starter_flutter` | エンジンのスレッド (`raster`、`platform`、`io`) と、`main` でのフレームのビルド時間。Flutter のタスクマネージャーがビルドに入っている場合 |

独自のソースは、このインターフェースを実装する Bean です。アプリケーションが自分で起動して管理する isolate のために使います。

```dart
@Component()
class EncoderLoads implements IsolateLoadSource {
  EncoderLoads(this.encoders);
  final EncoderPool encoders;

  @override
  List<IsolateLoad> loads() => [
    for (final encoder in encoders.all)
      IsolateLoad(
        name: encoder.name,
        kind: 'encoder',
        active: encoder.running,
        details: {'frames': encoder.frames},
      ),
  ];
}
```

`loads()` は読み取りのたびに、おそらく毎秒一回呼び出されます。すでに知っていることから答えてください。何かを待ってはいけません。

## 同じ名前の行は一つの行になる

ソースは、同じ名前の負荷を返すことで、別のソースが返す行に追加できます。Web サーバーがそうしています。サンプラーは `main` に遅れを与え、サーバーは `main` に実行中のリクエストを与え、読む側は両方を持つ一つの行を見ます。

マージでは、値ごとに、それを持つ最初のソースのものが使われます。そのため、後のソースは前のソースの `busy` を置き換えることはできず、欠けているものを埋めるだけです。`name` と `kind` は最初のソースのものです。詳細は両方のものが保持されます。同じ名前の詳細では、後のソースが優先されます。

## track

`Isolate.run` や `compute` で起動した isolate は、どのソースにも見えません。`track` がそれを表示します。

```dart
final report = await loads.track('report', Isolate.run(buildReport));
```

Future が動いている間、`report` という名前で、種類が `tracked`、`busy: 1`、`active: 1` の行があります。同じ名前の二つの追跡中の Future は、`active: 2` の一つの行になります。行は、最後の Future が完了したときに消えます。エラーで完了した場合も同じです。`track` は、渡された Future を返します。

これが示すのは、作業が動いていることであり、どのくらい負荷がかかっているかではありません。その isolate の中では何も計測されません。[タスクエグゼキューター](task-executor.md) に合う作業は、`track` なしで本物の行を得ます。

## 遅れと busy の計測方法

`IsolateLoadSampler` は、自分が動いている isolate を一つのタイマーで計測します。

- タイマーは `interval` (100 ms) ごとに期限が来ます。発火がどのくらい遅れたかが、遅れです。空いている isolate は時間どおりに発火します。80 ms 計算している isolate は 80 ms 遅れて発火します。
- `load()` は直近の `window` (5 秒) を見ます。`lag` はその中の遅れの平均、`maxLag` は最長のものです。
- `busy` は遅れから推定されます: 遅れの合計を、計測した時間 (インターバルと遅れの合計) で割ったものです。
- **誰かが読んでいる間だけ計測します。** 最初の `load()` はタイマーを開始するもので、まだ `lag` も `busy` もありません。`idleAfter` (30 秒) の間読み取りがなければ、タイマーは自分で止まります。誰も見ていないアプリケーションは、コストを払いません。

それではわからないこと:

- **`busy` はプロセッサー時間ではありません。** イベントループがどのくらい止められていたかです。コンパイルされたプログラムは、isolate がどのくらいプロセッサー時間を使っているかを問い合わせることができません。
- **二つのタイマーの間の短い作業は見えません。** タイマーが遅れるのは、期限の瞬間に何かが動いているときだけです。30 ms 計算して、次のタイマーの後まで休む isolate は、その分の遅れを示しません。短い作業がたくさんあると、実際より少ない `busy` として表示されます。一つの長い作業は、そのまま全部表示されます。
- **待つことは busy ではありません。** データベースを await している isolate のイベントループは空いています。`active` がどうであっても、遅れはなく、`busy` はゼロに近くなります。`active` が高く `busy` が低い場合、問題は isolate ではなく、isolate が待っているものにあります。
- **最初の数秒は欠けています。** 最初の読み取りの前には、何も計測されていません。
- **メモリーはプロセスのものです。** isolate ごとに分けることはできず、`main` だけが持ちます。ブラウザーでは使用中の JavaScript ヒープで、ブラウザーが伝える場合だけです。
- **知られている isolate だけが行になります。** ソースも `track` もない isolate は、コアを使っていても、タスクマネージャーにとっては存在しません。

タスクエグゼキューターの行には、別の `busy` があります。直近の 1 秒以上の間に、isolate がタスクを持っていた時間の割合です。await しているタスクは、その時間すべてが数えられます。計算されるのは多くても毎秒一回なので、複数の読み手は同じ値を見ます。

## サーバーの isolate のプールがある場合

ほかの isolate の行は、そこで計測されて最初の isolate に送られます。最初の isolate は、それぞれの最後の応答を保持します。

- 最初の isolate で `isolateLoads` を読むと、ほかの isolate にもう一度問い合わせます。多くても毎秒一回です。応答は次の読み取りのときにそろっているので、ほかの isolate の行は、読み取り一回分ほど古くなります。
- `await isolateReports.refresh()` は今すぐ問い合わせ、すべてが応答したとき、または 1 秒たっても応答しなかったものを除いて、完了します。行が最新でなければならないときは、この後に行を読んでください。
- **すべての行を持つのは、最初の isolate の `isolateLoads` だけです。** `isolate-2` では、この Bean は自分の行と自分のタスク用の isolate だけを返し、ほかには何も返しません。どの isolate で動くかわからないコードは、最初の isolate に問い合わせます。`await primaryIsolate.ask(IsolateLoadsHandler.handlerId)` は、どの isolate が問い合わせても、すべての行を最新の状態で JSON として返します ([最初の isolate に問い合わせる](primary-isolate.md) を参照)。Actuator のエンドポイントはそうしています。

## すべての isolate からのレポート

Bean が持つ数値は、isolate ごとに一つずつ持たれます。`IsolateReporter` Bean は、それをアプリケーション全体で使えるようにします。各 isolate は自分の isolate の中で問い合わせを受け、応答は最初の isolate の `IsolateReports`、つまり Bean `isolateReports` に保持されます。

```dart
@Component()
class BasketCount implements IsolateReporter {
  BasketCount(this.baskets);
  final Baskets baskets;

  @override
  String get id => 'baskets';

  @override
  Object? report() => baskets.open; // この isolate のもの
}

// 最初の isolate で:
await reports.refresh();
final open = reports.of('baskets', own: 'main');
// {main: 12, isolate-1: 9, isolate-2: 14}
```

| `IsolateReports` のメンバー | 意味 |
|---|---|
| `own()` | この isolate のレポーターが今伝えるもの。id ごと |
| `of(id, own: name)` | `id` という名前のレポートを isolate ごとに: 最初にこの isolate のものを、渡された名前で。次にほかの isolate のものを番号順に (`isolate-2` は `isolate-10` の前) |
| `refresh()` | ほかの isolate に今すぐ問い合わせる。プールがなければすぐに完了する |
| `put`、`remove` | プールが呼び出す |

- `report()` は JSON の値だけを返さなければなりません: 数値、テキスト、それらのリストとマップです。それ以外は isolate を越えられません。
- レポートは、最後の更新と同じだけ古くなります。タスクマネージャーを読むと更新されます。それ以外では `refresh()` を呼び出してください。
- プールがなければ、一つの isolate のレポートを持ち、読まれたときに問い合わせます。
- 最初の isolate で読んでください。ほかの isolate は自分のものしか持ちません。すべての isolate から応答するには、Web スターターの `RequestRates` のように、読み取りを [`PrimaryIsolateHandler`](primary-isolate.md) に入れます。

Web スターターの [毎秒のリクエスト数](../../spring-boot-starter-web/server/qps.md) は、この方法で作られています。各 isolate が数え、最初の isolate が合計します。

## Spring (Java) との対応

Spring に対応するものはありません。JVM のスレッドは Bean を共有するので、Bean に持たれた数値はアプリケーションのものです。最も近いのは Actuator の `threaddump` エンドポイントです。ここでは、各 isolate が自分を計測し、最初の isolate に伝えます。

## 関連項目

- [isolate](index.md)
- [タスクエグゼキューター](task-executor.md)
- [最初の isolate に問い合わせる](primary-isolate.md)
- [`isolates` エンドポイント](../../spring-boot-actuator/isolates.md)
- [Flutter アプリのタスクマネージャー](../../spring-boot-starter-flutter/isolates.md)
- [isolate のスケーリング](../../spring-boot-starter-web/server/scaling.md)
- [Observation と起動の計測](../observations/index.md)
