# 帳票設計書 5-プロセスリソース使用状況レポート

## 概要

本ドキュメントは、libuvライブラリにおける `uv_getrusage()` API関数の帳票設計書である。現在プロセスのリソース使用状況（CPU時間・メモリ・ページフォールト・コンテキストスイッチ等）をuv_rusage_t構造体に出力する機能について定義する。

### 本帳票の処理概要

本帳票は、POSIXの `getrusage(RUSAGE_SELF)` に相当する機能を、プラットフォーム間の差異を吸収した形で提供する。現在プロセスのリソース使用状況を包括的に取得する。

**業務上の目的・背景**：アプリケーションのリソース消費状況を把握し、CPU使用率・メモリ使用量・I/O操作量・コンテキストスイッチ回数等のシステムリソースメトリクスを監視するために使用する。パフォーマンス劣化の原因特定やキャパシティプランニングの基礎データとなる。

**帳票の利用シーン**：プロセスのリソース使用状況のモニタリング、パフォーマンスプロファイリング、メモリリークの検出補助（最大RSS値の推移監視）、I/O操作量の監視。

**主要な出力内容**：
1. ユーザーCPU時間（ru_utime）：ユーザモードで消費したCPU時間
2. システムCPU時間（ru_stime）：カーネルモードで消費したCPU時間
3. 最大常駐セットサイズ（ru_maxrss）：キロバイト単位
4. ページフォールト情報（ru_minflt, ru_majflt）
5. コンテキストスイッチ回数（ru_nvcsw, ru_nivcsw）
6. ブロックI/O操作回数（ru_inblock, ru_oublock）

**帳票の出力タイミング**：`uv_getrusage(&rusage)` 呼び出し時に即座に出力される。

**帳票の利用者**：運用監視チーム、パフォーマンスエンジニア、SRE。

## 帳票種別

リソース使用状況レポート（構造体出力）

## 利用画面

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

## 出力形式

### 基本仕様

| 項目 | 内容 |
|-----|------|
| ファイル形式 | メモリ構造体（uv_rusage_t） |
| 出力方法 | 構造体フィールドへの値格納 |

## 帳票レイアウト

### 明細部

| No | 項目名 | 説明 | データ取得元 | 表示形式 | 備考 |
|----|-------|------|-------------|---------|------|
| 1 | ru_utime | ユーザーCPU時間 | getrusage().ru_utime | uv_timeval_t（秒+マイクロ秒） | |
| 2 | ru_stime | システムCPU時間 | getrusage().ru_stime | uv_timeval_t（秒+マイクロ秒） | |
| 3 | ru_maxrss | 最大常駐セットサイズ | getrusage().ru_maxrss | uint64_t（KB） | macOSはバイト単位を1024で除算、Solarisはページ単位をKBに変換 |
| 4 | ru_ixrss | 共有メモリサイズ積分値 | getrusage().ru_ixrss | uint64_t | |
| 5 | ru_idrss | 非共有データサイズ積分値 | getrusage().ru_idrss | uint64_t | |
| 6 | ru_isrss | 非共有スタックサイズ積分値 | getrusage().ru_isrss | uint64_t | |
| 7 | ru_minflt | ソフトページフォールト | getrusage().ru_minflt | uint64_t | |
| 8 | ru_majflt | ハードページフォールト | getrusage().ru_majflt | uint64_t | |
| 9 | ru_nswap | スワップ回数 | getrusage().ru_nswap | uint64_t | |
| 10 | ru_inblock | ブロック入力操作 | getrusage().ru_inblock | uint64_t | |
| 11 | ru_oublock | ブロック出力操作 | getrusage().ru_oublock | uint64_t | |
| 12 | ru_msgsnd | 送信IPCメッセージ | getrusage().ru_msgsnd | uint64_t | |
| 13 | ru_msgrcv | 受信IPCメッセージ | getrusage().ru_msgrcv | uint64_t | |
| 14 | ru_nsignals | 受信シグナル数 | getrusage().ru_nsignals | uint64_t | |
| 15 | ru_nvcsw | 自発的コンテキストスイッチ | getrusage().ru_nvcsw | uint64_t | |
| 16 | ru_nivcsw | 非自発的コンテキストスイッチ | getrusage().ru_nivcsw | uint64_t | |

## 出力条件

### 抽出条件

| 条件名 | 説明 | 必須 |
|-------|------|-----|
| rusageポインタ | 結果を格納するuv_rusage_t構造体へのポインタ | Yes |

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

### 参照テーブル一覧

| テーブル名（データ構造） | 用途 | 結合条件 |
|-----------|------|---------|
| struct rusage | POSIXリソース使用状況 | getrusage(RUSAGE_SELF, &usage)で取得 |

## 計算仕様

### 計算項目一覧

| 項目名 | 計算式 | 端数処理 | 備考 |
|-------|-------|---------|------|
| ru_maxrss正規化（macOS） | usage.ru_maxrss / 1024 | 整数除算（切り捨て） | macOS/iOSはバイト単位で報告するため |
| ru_maxrss正規化（Solaris） | usage.ru_maxrss * (getpagesize() / 1024) | 整数乗算 | Solarisはページ単位で報告するため |

## 処理フロー

### 出力フロー

```mermaid
flowchart TD
    A[uv_getrusage呼び出し] --> B[uv__getrusage RUSAGE_SELF呼び出し]
    B --> C[getrusage RUSAGE_SELF 実行]
    C --> D{成功?}
    D -->|No| E[UV__ERR errno を返却]
    D -->|Yes| F[ru_utimeとru_stimeをコピー]
    F --> G[その他フィールドをコピー]
    G --> H{macOS?}
    H -->|Yes| I[ru_maxrss /= 1024]
    H -->|No| J{Solaris?}
    J -->|Yes| K[ru_maxrss *= getpagesize/1024]
    J -->|No| L[0を返却]
    I --> L
    K --> L
```

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 表示メッセージ | 対処方法 |
|----------|---------|--------------|---------|
| システムコール失敗 | getrusage()がエラーを返した場合 | N/A | UV__ERR(errno)をエラーコードとして返却 |

## パフォーマンス要件

| 項目 | 内容 |
|-----|------|
| 想定データ件数 | 1件（固定） |
| 目標出力時間 | マイクロ秒オーダー（syscall 1回） |
| 同時出力数上限 | N/A |

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

プロセスのリソース使用状況は機密情報ではないが、サイドチャネル攻撃の一部としてタイミング情報が悪用される可能性がある。

## 備考

- __MVS__（z/OS）および__HAIKU__ではru_maxrss〜ru_nivcsw のフィールドは設定されない
- macOSではru_maxrssがバイト単位で報告されるため、1024で除算してKB単位に正規化する
- SolarisではRu_maxrssがページ単位で報告されるため、getpagesize()/1024を乗じてKB単位に変換する
- Windows版は別実装（src/win/util.c）

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | uv.h | `include/uv.h` | uv_rusage_t構造体（1291-1308行目）の全16フィールドを確認 |
| 1-2 | uv.h | `include/uv.h` | uv_timeval_t構造体（374-377行目）のtv_sec, tv_usecメンバ |

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | core.c | `src/unix/core.c` | uv_getrusage()（1139-1141行目）がuv__getrusage(RUSAGE_SELF, rusage)を呼び出すことを確認 |

#### Step 3: 内部実装を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | core.c | `src/unix/core.c` | uv__getrusage()（1097-1136行目）の全体を読む |

**主要処理フロー**:
- **1100行目**: getrusage(who, &usage)でシステムコール実行
- **1103-1107行目**: ru_utime, ru_stimeのtv_sec, tv_usecをコピー
- **1109-1124行目**: __MVS__と__HAIKU__以外で残りフィールドをコピー
- **1129-1133行目**: プラットフォーム別のru_maxrss正規化

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

```
uv_getrusage(rusage)                          [src/unix/core.c:1139]
    |
    +-- uv__getrusage(RUSAGE_SELF, rusage)    [src/unix/core.c:1097]
            |
            +-- getrusage(RUSAGE_SELF, &usage) [POSIXシステムコール]
```

### データフロー図

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

getrusage()               uv__getrusage()                     uv_rusage_t*
  struct rusage -------->  フィールドコピー                    .ru_utime
                           プラットフォーム正規化              .ru_stime
                           (macOS: /1024)                     .ru_maxrss
                           (Solaris: *pagesize/1024)          .ru_minflt  ...
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| uv.h | `include/uv.h` | ヘッダ | uv_rusage_t構造体定義、API宣言 |
| core.c | `src/unix/core.c` | ソース | Unix版uv_getrusage()、uv__getrusage()実装 |
| util.c | `src/win/util.c` | ソース | Windows版実装（参考） |
