# 画面設計書 30-メトリクス

## 概要

本ドキュメントは、libuvドキュメントサイトにおけるメトリクス（`uv_metrics_t`）APIリファレンスページの画面設計書である。イベントループのメトリクス取得機能のAPI定義を記載する。

### 本画面の処理概要

本ページは、libuvにおけるイベントループのメトリクス（計測情報）取得APIのリファレンスを提供する。イベントループのイテレーション数、処理イベント数、待機イベント数、アイドル時間などの内部統計情報を取得するためのAPIを定義する。

**業務上の目的・背景**：イベントループのパフォーマンス監視・チューニングには、ループの内部動作状態を計測する必要がある。メトリクスAPIはイベントループのイテレーション数、イベント処理数、アイドル時間等の統計情報を提供し、アプリケーションのパフォーマンス分析やボトルネック特定に利用される。

**画面へのアクセス方法**：トップページからAPIドキュメント一覧（api.rst）を経由し、メトリクスリンクをクリックして本ページに遷移する。

**主要な操作・処理内容**：
1. メトリクス情報取得（`uv_metrics_info`）のAPI仕様確認
2. アイドル時間取得（`uv_metrics_idle_time`）のAPI仕様確認
3. uv_metrics_t構造体のフィールド確認

**画面遷移**：
- 遷移元：APIドキュメント一覧（api.rst）
- 関連：イベントループ設定（loop.rst の uv_loop_configure / UV_METRICS_IDLE_TIME）

**権限による表示制御**：なし（公開ドキュメント）

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 175 | メトリクス情報取得 | 主機能 | uv_metrics_info()によるイベントループメトリクス取得のAPI定義 |
| 176 | アイドル時間取得 | 主機能 | uv_metrics_idle_time()によるイベントループアイドル時間取得のAPI定義 |

## 画面種別

APIリファレンス（詳細表示）

## URL/ルーティング

`/docs/src/metrics.rst` (Sphinx生成後: `/metrics.html`)

## 入出力項目

| API関数 | パラメータ名 | 型 | 入出力 | 説明 |
|---------|-------------|-----|--------|------|
| uv_metrics_idle_time | loop | uv_loop_t* | 入力 | イベントループ |
| uv_metrics_idle_time | (返値) | uint64_t | 出力 | 累積アイドル時間 |
| uv_metrics_info | loop | uv_loop_t* | 入力 | イベントループ |
| uv_metrics_info | metrics | uv_metrics_t* | 出力 | メトリクス情報格納先 |

## 表示項目

| セクション | 表示内容 | 説明 |
|-----------|---------|------|
| タイトル | Metrics operations | ページタイトル |
| 概要説明 | libuv provides a metrics API... | メトリクスAPIの概要 |
| Data types | uv_metrics_t | メトリクスデータ型の定義（構造体定義含む） |
| Public members | loop_count, events, events_waiting | 公開メンバーフィールド |
| API | uv_metrics_idle_time, uv_metrics_info | メトリクス取得の全API |

## イベント仕様

### 1-メトリクス取得タイミング

uv_metrics_info()はuv_prepare_cbコールバック内で呼び出すことが推奨される。これにより、メトリクスカウンターの不整合を防ぐことができる。

### 2-アイドル時間計測の有効化

uv_metrics_idle_time()を使用するには、事前にuv_loop_configureでUV_METRICS_IDLE_TIMEオプションを設定する必要がある。設定前のアイドル時間は累積されない。

## データベース更新仕様

### 操作別データベース影響一覧

該当なし（本プロジェクトはCライブラリであり、データベースは使用しない）

## メッセージ仕様

| メッセージ種別 | 条件 | 内容 |
|--------------|------|------|
| note | uv_metrics_idle_time | UV_METRICS_IDLE_TIMEでループ設定後にアイドル時間の累積が開始される |
| note | uv_metrics_t | uv_prepare_cbで取得することで不整合を防止できる |
| versionadded | uv_metrics_idle_time | v1.39.0で追加 |
| versionadded | uv_metrics_info | v1.45.0で追加 |

## 例外処理

特にエラーコードの定義はない。uv_metrics_idle_time()はスレッドセーフで呼び出し可能。

## 備考

- uv_metrics_tのreservedフィールドはプライベートであり、将来の拡張用に予約されている
- loop_countはイベントループのイテレーション回数
- eventsはイベントハンドラによって処理されたイベント数
- events_waitingはイベントプロバイダ呼び出し時に待機していたイベント数
- uv_metrics_idle_time()はスレッドセーフ
- uv_metrics_idle_time()の戻り値はカーネルのイベントプロバイダ（例：epoll_wait）でのアイドル時間の累積値

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | uv_metrics_tの構造体定義（loop_count, events, events_waiting） |

**読解のコツ**: uv_metrics_tのreservedフィールド（uint64_t* reserved[13]）はプライベートで将来の拡張用。公開フィールドはloop_count、events、events_waitingの3つ。

#### Step 2: メトリクス取得の実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | uv-common.c | `src/uv-common.c` | uv_metrics_idle_time()、uv_metrics_info()の実装 |

**主要処理フロー**:
- `uv_metrics_idle_time()`: loop内部のメトリクスカウンターから累積アイドル時間を取得
- `uv_metrics_info()`: loop内部のメトリクスをuv_metrics_t構造体にコピー

#### Step 3: メトリクス収集の仕組みを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | core.c (Unix) | `src/unix/core.c` | イベントループ内でのメトリクス更新処理 |
| 3-2 | core.c (Win) | `src/win/core.c` | Windows側のメトリクス更新処理 |

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

```
uv_loop_configure(UV_METRICS_IDLE_TIME) [設定]
    |
    +-- アイドル時間計測を有効化

uv_run() [イベントループ実行]
    |
    +-- [各イテレーション]
    |       +-- loop_count++
    |       +-- events++/events_waiting++ [イベント処理時]
    |       +-- idle_time += (ポーリング待機時間) [IDLE_TIME有効時]
    |
    +-- uv_metrics_idle_time() [スレッドセーフ取得]
    |       +-- return loop->metrics.idle_time
    |
    +-- uv_metrics_info() [構造体コピー]
            +-- metrics->loop_count = loop->metrics.loop_count
            +-- metrics->events = loop->metrics.events
            +-- metrics->events_waiting = loop->metrics.events_waiting
```

### データフロー図

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

イベントループ実行 --> 内部メトリクスカウンター更新
                              |
                              v
uv_metrics_info() --> カウンターのコピー ------> uv_metrics_t
                                                  (loop_count,
                                                   events,
                                                   events_waiting)

uv_metrics_idle_time() --> アイドル時間読取 --> uint64_t
                                                (累積アイドル時間)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| metrics.rst | `docs/src/metrics.rst` | テンプレート | メトリクスページのSphinxソース |
| uv.h | `include/uv.h` | ソース | uv_metrics_tの公開API定義 |
| uv-common.c | `src/uv-common.c` | ソース | メトリクス取得関数の実装 |
| core.c (Unix) | `src/unix/core.c` | ソース | Unix系イベントループでのメトリクス更新 |
| core.c (Win) | `src/win/core.c` | ソース | Windows系イベントループでのメトリクス更新 |
| api.rst | `docs/src/api.rst` | テンプレート | API一覧ページ（遷移元） |
| loop.rst | `docs/src/loop.rst` | テンプレート | イベントループページ（UV_METRICS_IDLE_TIME設定） |
