
# 毎秒のリクエスト数

デバッグ機能 `qps` は、サーバーが応答するリクエストを数え、数秒ごとに、毎秒のリクエスト数、かかった時間、実行中の数、失敗した数を求めます。isolate ごとと、全体の合計についてです。間隔ごとに一行をログに出し、アクチュエーターの [`qps` エンドポイント](../../spring-boot-actuator/qps.md) は、リクエストを受け取ったのがどの isolate でも、同じ数値を JSON で応答します。

これがビルドに入るのは `spring.web.debug.qps.enabled: true` のときだけです。この行がなければ、アプリケーションにはリクエストを数えるコードがありません。

## 使う理由

「サーバーはどれだけ受けているのか」は、負荷テストでも、サーバーが遅い晩にも、最初に出る問いです。この機能は、それが起きている間に、一行で、isolate ごとに答えます。そのため、偏って応答している [プール](isolates.md) がわかります。

これはデバッグ機能であって、メトリクスのシステムではありません。持つのは最後の一つのウィンドウだけで、時間を追った記録は持ちません。

## 例

```yaml
# lib/resources/application.yml
spring:
  web:
    debug:
      qps:
        enabled: true       # ビルドが読む
        log-interval: 10s
```

```bash
dart run build_runner build   # プロパティはここで読まれる
dart run bin/main.dart
```

負荷がかかると、最初の isolate は `spring.web.qps` に `info` でログを出します。

```text
1250.4 requests/s (p50 1.1 ms, p99 9.2 ms), 14 in flight, 0 errors; main 412.0, isolate-1 420.2, isolate-2 418.2
```

isolate が一つのときは、行はエラーの後で終わります。リクエストがなく、実行中のものもない間隔では、何もログに出ません。

## ビルドが決める

`spring.web.debug.qps.enabled` は [ビルドプロパティ](../../spring-core-dart-generator/optimizations/build-conditions.md) です。ジェネレーターは `build_runner` の実行時にそれを読み、この機能のモジュールをアプリケーションに入れるか、入れないかを決めます。

| `spring.web.debug.qps.enabled` | アプリケーション |
|---|---|
| `true` | 数えるフィルターと `RequestRates` を持つ。どのビルドでも |
| `false`、または未設定 | そのコードを一切持たない |

- `application.yml` または `application.properties` に、プロファイルなしで設定してください。ビルドは、プロファイルのファイル、環境変数、`--dart-define` の値を読みません。
- 変更した後は `build_runner` をもう一度実行してください。
- **実行時のプロパティでは、オンにもオフにもできません。** このモジュールに実行時の条件はありません。ビルドが入れたものが動きます。
- このモジュールは、Web スターター自体と同じく、ネイティブ専用です。ブラウザービルドには一切入りません。

## 数えられるもの

`RequestRateFilter` (Bean `requestRateFilter`) はチェーンの最初のフィルターで、他のすべてを囲みます。セキュリティのフィルターチェーン、ハンドラー、応答の書き込みです。リクエストごとに次のものを数えます。

| 数えるもの | 意味 |
|---|---|
| requests | 応答されたリクエスト |
| errors | `5xx` のステータスで応答されたもの、またはエラーで終わったもの (自分のステータスを示すエラーはそのステータスで、その他は `500` として数える) |
| in flight | 今応答中のリクエスト |
| latency | フィルターの開始から終了までの時間。バケットに分ける |

これに含まれないもの:

- **リクエストが isolate を待った時間。** フィルターは、isolate がそのリクエストに取りかかったときに始まります。他のリクエストの後ろで 200 ms 待ち、2 ms で応答されたリクエストは、2 ms として数えられます。待ち時間は [遅れ (lag)](../../spring-core-dart/isolates/load.md#遅れと-busy-の計測方法) として現れ、ここには現れません。
- **サーバーが満杯だったために拒否されたリクエスト。** それらはどのフィルターよりも先に応答されます ([過負荷](overload.md))。タスクマネージャーの `refused` がそれです。
- **ネットワーク。** この時間はサーバーのものであって、クライアントのものではありません。

## パーセンタイル

各リクエストのレイテンシーは、一つのバケットに入ります。バケットの上限は 100 µs から始まり、それぞれが前のものの 1.5 倍で、およそ一分まで続きます。最後のバケットは、それより遅いものを受け取ります。

パーセンタイルは、そのリクエストが入ったバケットの上限です。つまり `p99 9.2 ms` は、リクエストの 99 % が 9.2 ms 以内に応答されたという意味で、実際の値は、その上限と一つ前の上限 (その三分の二) の間のどこかにあります。2 ms と 20 ms と 200 ms を見分けるには十分です。8 ms と 9 ms を比べるには十分ではありません。

合計のパーセンタイルは、すべての isolate のバケットを足し合わせたものから求めます。isolate ごとのパーセンタイルの平均ではありません。

## ウィンドウ

`RequestRates` (Bean `requestRates`) は、アプリケーションの最初の isolate にあります。`spring.web.debug.qps.log-interval` ごとに isolate にカウントを問い合わせ、前回の確認との差を保持します。それがウィンドウです。

- 毎秒のリクエスト数は、ウィンドウのリクエスト数をその長さで割ったものです。
- リクエストは、応答されたウィンドウで数えられます。
- 再び起動された isolate は、ゼロから数えます。そのウィンドウは、今持っている数です。
- [スケーリング](scaling.md) で追加または削除された isolate は、行に現れるか、行から消えます。
- `in flight` は、ウィンドウの終わりの時点の数です。

コードでは、ウィンドウは最初の isolate の他の応答と同じように問い合わせます。そのため、同じコードがすべての isolate で動きます。

```dart
@RestController()
class LoadController {
  LoadController(this.primary);
  final PrimaryIsolate primary;

  // 最後のウィンドウを JSON で: /actuator/qps が応答するもの。最初のウィンドウの前は null。
  @GetMapping('/internal/load')
  Future<Object?> load() => primary.ask(RequestRates.handlerId);

  // ウィンドウを今終わらせる: /actuator/qps/now が応答するもの。
  @GetMapping('/internal/load/now')
  Future<Object?> now() => primary.ask(RequestRates.handlerId, 'now');
}
```

`RequestRates.handlerId` は `web.qps` です。[最初の isolate に問い合わせる](../../spring-core-dart/isolates/primary-isolate.md) を参照してください。

最初の isolate の Bean は、`RequestRates` そのものを受け取り、型付きの値を読めます。

```dart
@Component()
@ConditionalOnPrimaryIsolate()
class RateWatch {
  RateWatch(this.rates);
  final RequestRates rates;

  @Scheduled(fixedRate: Duration(minutes: 1))
  void check() {
    final p99 = rates.last?.total.percentile(0.99);
    if (p99 != null && p99 > const Duration(seconds: 1)) {
      alerts.slow(p99);
    }
  }
}
```

| メンバー | 意味 |
|---|---|
| `RequestRates.last` | 最後のウィンドウ。`RequestRateWindow`。最初の間隔が過ぎる前は `null` |
| `RequestRates.look()` | ウィンドウを今終わらせ、ログに出し、それを返す |
| `RequestRateWindow.total` | すべての isolate の合計。`RequestRate` |
| `RequestRateWindow.isolates` | 名前ごとの各 isolate。最初の isolate が先頭 |
| `RequestRate.qps`、`requests`、`errors`、`active`、`seconds` | ウィンドウの数値 |
| `RequestRate.percentile(share)` | リクエストのその割合がそれ未満で応答されたレイテンシー (`0.5`、`0.99`)。リクエストがなければ `null` |

`RequestRates` Bean は、最初の isolate にだけ存在します。それを受け取る Bean も、そこにだけ存在しなければなりません (`@ConditionalOnPrimaryIsolate()`)。そうでなければ他の isolate が起動しません。すべての isolate にある Bean は、`PrimaryIsolate` を通して問い合わせます。

## ログに出さない

この行は `info` でログに出ます。行を出さずに、カウントとエンドポイントだけを残すには:

```yaml
logging:
  level:
    spring.web.qps: warn
```

## プロパティ

| キー | 型 | デフォルト | 意味 |
|---|---|---|---|
| `spring.web.debug.qps.enabled` | `bool` | `false` | アプリケーションがリクエストを数えるかどうか。ジェネレーターが読む: `true` でなければ、ビルドにこの機能のコードは一切入らない |
| `spring.web.debug.qps.log-interval` | `Duration` | `10s` | ウィンドウの長さ: レートを求めてログに出す頻度。`0`: 何もログに出さず、ウィンドウは二回の確認 (`look()`、`/actuator/qps/now`) の間の時間になる |

## Spring (Java) との対応

Spring で対応するものは、Micrometer の `http.server.requests` タイマーです。アクチュエーターの `metrics` エンドポイントや監視システムを通して読みます。こちらは意図して小さくしてあります。ウィンドウは一つ、行は一つで、求めなければビルドにコードは入りません。

## 関連項目

- [`qps` エンドポイント](../../spring-boot-actuator/qps.md)
- [isolate のプール](isolates.md)
- [過負荷](overload.md)
- [フィルター](../filters.md)
- [isolate の負荷](../../spring-core-dart/isolates/load.md)
- [最初の isolate に問い合わせる](../../spring-core-dart/isolates/primary-isolate.md)
- [ビルドから外されるモジュール](../../spring-core-dart-generator/optimizations/build-conditions.md)
- [負荷テスト](../../../docs/load-testing.md)
