# 帳票設計書 3-イベントループメトリクス情報

## 概要

本ドキュメントは、libuvライブラリにおける `uv_metrics_info()` API関数の帳票設計書である。イベントループの統計情報（ループ回数・イベント数・待機中イベント数）をuv_metrics_t構造体に出力する機能について定義する。

### 本帳票の処理概要

本帳票は、libuvイベントループの動作統計情報を構造体に格納して返却する機能を提供する。

**業務上の目的・背景**：イベントループの動作状況をモニタリングし、パフォーマンス問題の検出やループの健全性評価に利用する。ループ回数の急激な増加はビジーループの兆候であり、イベント数と待機イベント数の差はイベント処理の遅延を示す。これらの指標はアプリケーションのパフォーマンスチューニングに不可欠である。

**帳票の利用シーン**：アプリケーションのパフォーマンスモニタリング、イベントループのビジーループ検出、イベント処理スループットの計測、運用監視ダッシュボードへの統計情報提供。

**主要な出力内容**：
1. loop_count（uint64_t）：イベントループの実行回数
2. events（uint64_t）：処理されたイベントの累計数
3. events_waiting（uint64_t）：ポーリング時に待機していたイベントの累計数

**帳票の出力タイミング**：`uv_metrics_info(loop, metrics)` の呼び出し時に即座にメモリコピーで出力される。スナップショット取得であり、呼び出し時点の値が返される。

**帳票の利用者**：アプリケーション開発者、運用監視チーム、パフォーマンスエンジニア。

## 帳票種別

メトリクスレポート（構造体出力）

## 利用画面

| 画面No | 画面名 | URL/ルーティング | 出力操作 |
|--------|--------|-----------------|---------|
| N/A | N/A（C API呼び出し） | N/A | `uv_metrics_info(loop, &metrics)` 関数呼び出し |

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | メモリ構造体（uv_metrics_t） |
| 用紙サイズ | N/A |
| 向き | N/A |
| ファイル名 | N/A（メモリ上の構造体に出力） |
| 出力方法 | memcpy()によるバイナリコピー |
| 文字コード | N/A（バイナリデータ） |

## 帳票レイアウト

### レイアウト概要

uv_metrics_t構造体のフィールドとして出力される。

### 明細部

| No | 項目名 | 説明 | データ取得元 | 表示形式 | サイズ |
|----|-------|------|-------------|---------|------|
| 1 | loop_count | イベントループの実行回数 | loop_metrics->metrics.loop_count | uint64_t | 8バイト |
| 2 | events | 処理済みイベント累計 | loop_metrics->metrics.events | uint64_t | 8バイト |
| 3 | events_waiting | 待機中イベント累計 | loop_metrics->metrics.events_waiting | uint64_t | 8バイト |
| 4 | reserved[13] | 将来拡張用予約領域 | N/A | uint64_t*[13] | 104バイト |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| イベントループ | メトリクスを取得するイベントループ | Yes |

### ソート順

N/A（単一構造体出力）

### 改ページ条件

N/A

## データベース参照仕様

### 参照テーブル一覧

| テーブル名（データ構造） | 用途 | 結合条件 |
|-----------|------|---------|
| uv__loop_internal_fields_t | ループ内部フィールドからloop_metricsを取得 | loop->internal_fields経由 |
| uv__loop_metrics_t | メトリクスデータの格納 | uv__get_loop_metrics()マクロ経由 |

### テーブル別参照項目詳細

#### uv__loop_metrics_t

| 参照項目 | 帳票項目との対応 | 取得条件 | 備考 |
|---------|----------------|---------|------|
| metrics.loop_count | loop_count | memcpyで一括コピー | uv__metrics_inc_loop_count()でインクリメント |
| metrics.events | events | memcpyで一括コピー | uv__metrics_inc_events()でインクリメント |
| metrics.events_waiting | events_waiting | memcpyで一括コピー | uv__metrics_inc_events_waiting()でインクリメント |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| メトリクスコピー | memcpy(metrics, &loop_metrics->metrics, sizeof(*metrics)) | N/A | 構造体全体の一括コピー |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[uv_metrics_info呼び出し] --> B[uv__get_loop_metricsでloop_metricsポインタ取得]
    B --> C[memcpyでmetrics構造体にコピー]
    C --> D[0を返却して終了]
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| N/A | 本関数は常に0（成功）を返す | N/A | N/A |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 1件（固定） |
| 目標出力時間 | ナノ秒オーダー（memcpyのみ） |
| 同時出力数上限 | N/A |

## セキュリティ考慮事項

メトリクスデータ自体にセンシティブな情報は含まれない。ただしloop_countやeventsの値からアプリケーションの負荷状況を推測できる可能性がある。

## 備考

- メトリクスのインクリメントはスレッドセーフではない（イベントループスレッドからのみ更新される前提）
- reserved[13]フィールドは将来の拡張用であり、現在は使用されない
- 本関数はロックを取得しないため、provider_idle_timeの取得にはuv_metrics_idle_time()を別途使用する必要がある

---

## コードリーディングガイド

本帳票を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | uv_metrics_t構造体（1390-1396行目）のフィールド定義（loop_count, events, events_waiting, reserved） |
| 1-2 | uv-common.h | `src/uv-common.h` | uv__loop_metrics_t構造体（399-404行目）がuv_metrics_tを含む内部構造体であることを確認 |
| 1-3 | uv-common.h | `src/uv-common.h` | uv__loop_internal_fields_t構造体（430-439行目）がloop_metricsを含むことを確認 |

**読解のコツ**: `uv__get_loop_metrics(loop)` マクロ（369-370行目）は `loop->internal_fields` を `uv__loop_internal_fields_t*` にキャストし、その `loop_metrics` メンバへのポインタを返す。この間接参照チェーンを理解することが重要。

#### Step 2: エントリーポイントを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | uv-common.c | `src/uv-common.c` | uv_metrics_info()（1033-1039行目）の実装を確認 |

**主要処理フロー**:
1. **1034-1036行目**: memcpy()で `uv__get_loop_metrics(loop)->metrics` から呼び出し元の `metrics` にデータをコピー
2. **1038行目**: 0（成功）を返却

#### Step 3: メトリクスの更新メカニズムを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | uv-common.h | `src/uv-common.h` | uv__metrics_inc_loop_count()マクロ（372-375行目） |
| 3-2 | uv-common.h | `src/uv-common.h` | uv__metrics_inc_events()マクロ（377-380行目） |
| 3-3 | uv-common.h | `src/uv-common.h` | uv__metrics_inc_events_waiting()マクロ（382-385行目） |

### プログラム呼び出し階層図

```
uv_metrics_info(loop, metrics)                [src/uv-common.c:1033]
    |
    +-- uv__get_loop_metrics(loop)            [src/uv-common.h:369]  マクロ展開
    |       |
    |       +-- uv__get_internal_fields(loop) [src/uv-common.h:366]  マクロ展開
    |
    +-- memcpy()                              [標準ライブラリ]
```

### データフロー図

```
[入力]                        [処理]                         [出力]

uv_loop_t                     uv_metrics_info()              uv_metrics_t*
  .internal_fields             1033-1039行目                  (呼び出し元の構造体)
       |                                                      .loop_count
       +-> uv__loop_internal_fields_t                         .events
              .loop_metrics                                    .events_waiting
                 .metrics -----> memcpy() -----> metrics
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| uv.h | `include/uv.h` | ヘッダ | uv_metrics_t構造体定義、API宣言 |
| uv-common.h | `src/uv-common.h` | 内部ヘッダ | uv__loop_metrics_t構造体、uv__get_loop_metrics()マクロ、メトリクスインクリメントマクロ |
| uv-common.c | `src/uv-common.c` | ソース | uv_metrics_info()実装 |
