# 画面設計書 153-I/Oレイテンシ

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるI/Oレイテンシ監視機能の設計を定義する。SQL Serverインスタンス上のすべてのデータベースファイルに対するI/Oパフォーマンス統計を取得し、ストレージボトルネックの特定を支援する。

### 本画面の処理概要

本機能は、SQL Serverのsys.dm_io_virtual_file_statsを照会し、各データベースファイルのI/Oレイテンシ（読み取り/書き込み遅延）を計測・分析するための詳細な統計情報を提供する。

**業務上の目的・背景**：データベースのパフォーマンス問題の多くはストレージI/Oに起因する。本機能は、Paul Randalのパフォーマンスチューニング手法に基づき、どのデータベースファイルが高いI/O待機時間を経験しているかを迅速に特定できる。これにより、ストレージサブシステムの問題や特定ファイルの配置最適化の必要性を診断できる。

**画面へのアクセス方法**：PowerShellコンソールまたはスクリプトから以下のコマンドを実行してアクセスする：
- `Get-DbaIoLatency -SqlInstance <インスタンス名>`

**主要な操作・処理内容**：
1. sys.dm_io_virtual_file_statsから全データベースファイルのI/O統計を取得
2. sys.master_filesとの結合でファイルパス情報を取得
3. 読み取りレイテンシ、書き込みレイテンシ、総合レイテンシの計算
4. 平均バイト/読み取り、平均バイト/書き込みの計算
5. ファイルごとのI/O回数、バイト数、待機時間の表示

**画面遷移**：
- 本機能はスタンドアロンで動作し、他の機能への直接的な画面遷移はない
- パイプラインでConvertTo-DbaDataTable等と連携可能

**権限による表示制御**：
- SQL Server接続権限が必要
- sys.dm_io_virtual_file_stats への VIEW SERVER STATE 権限が必要

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 126 | Get-DbaIoLatency | 主機能 | I/Oレイテンシ統計の取得 |

## 画面種別

一覧 / 診断情報表示

## URL/ルーティング

PowerShellコマンドレット:
- `Get-DbaIoLatency`

## 入出力項目

### Get-DbaIoLatency パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|------|------|------|
| SqlInstance | DbaInstance[] | Yes | 接続先SQL Serverインスタンス |
| SqlCredential | PSCredential | No | SQL Server認証用資格情報 |
| EnableException | switch | No | 例外処理の有効化 |

## 表示項目

### Get-DbaIoLatency 出力プロパティ

| プロパティ名 | 型 | 説明 | デフォルト表示 |
|-------------|------|------|---------------|
| ComputerName | string | SQL Serverインスタンスのコンピュータ名 | Yes |
| InstanceName | string | SQL Serverインスタンス名 | Yes |
| SqlInstance | string | 完全なSQL Serverインスタンス名 | Yes |
| DatabaseId | int | データベースID | Yes |
| DatabaseName | string | データベース名 | Yes |
| FileId | int | ファイルID | Yes |
| PhysicalName | string | ファイルの物理パス | Yes |
| NumberOfReads | long | 読み取り操作の総数 | Yes |
| IoStallRead | long | 読み取り待機時間（ミリ秒） | Yes |
| NumberOfwrites | long | 書き込み操作の総数 | Yes |
| IoStallWrite | long | 書き込み待機時間（ミリ秒） | Yes |
| IoStall | long | 総I/O待機時間（ミリ秒） | Yes |
| NumberOfBytesRead | long | 読み取りバイト数 | Yes |
| NumberOfBytesWritten | long | 書き込みバイト数 | Yes |
| SampleMilliseconds | long | インスタンス起動からの経過時間（ミリ秒） | Yes |
| SizeOnDiskBytes | long | ディスク上のファイルサイズ（バイト） | Yes |
| FileHandle | IntPtr | ファイルハンドル | No |
| ReadLatency | decimal | 平均読み取りレイテンシ（ミリ秒） | No |
| WriteLatency | decimal | 平均書き込みレイテンシ（ミリ秒） | No |
| Latency | decimal | 平均総合レイテンシ（ミリ秒） | No |
| AvgBPerRead | decimal | 平均バイト/読み取り | No |
| AvgBPerWrite | decimal | 平均バイト/書き込み | No |
| AvgBPerTransfer | decimal | 平均バイト/転送 | No |

## イベント仕様

### 1-Get-DbaIoLatency実行

1. Connect-DbaInstanceでSQL Serverインスタンスに接続（最小バージョン: SQL Server 2005）
2. sys.dm_io_virtual_file_statsとsys.master_filesを結合するクエリを実行
3. レイテンシ計算（ゼロ除算対応）を含むCASE式で統計を算出
4. 各ファイルの結果をPSCustomObjectとして出力
5. Select-DefaultViewで非表示プロパティを設定

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Get-DbaIoLatency | sys.dm_io_virtual_file_stats | SELECT | ファイルI/O統計取得 |
| Get-DbaIoLatency | sys.master_files | SELECT | ファイルメタデータ取得 |

### テーブル別更新項目詳細

本機能は読み取り専用のため、データベースへの更新は発生しない。

## メッセージ仕様

| メッセージID | レベル | 条件 | メッセージ内容 |
|-------------|--------|------|---------------|
| - | Debug | SQL実行時 | SQLクエリテキスト |
| - | Error | 接続失敗 | "Failure" |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| SQL Server接続失敗 | ConnectionError カテゴリでStop-Function実行、処理継続 |
| SQL Server 2005未満 | MinimumVersion 9 により自動的にスキップ |
| Test-FunctionInterrupt | 処理中断 |

## 備考

- レイテンシ計算はゼロ除算に対応（I/O発生なしの場合は0を返す）
- ReadLatency = IoStallRead / NumberOfReads
- WriteLatency = IoStallWrite / NumberOfwrites
- Latency = IoStall / (NumberOfReads + NumberOfwrites)
- 参考資料:
  - https://www.sqlskills.com/blogs/paul/how-to-examine-io-subsystem-latencies-from-within-sql-server/
  - https://www.sqlskills.com/blogs/paul/capturing-io-latencies-period-time/

---

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

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

### 推奨読解順序

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

I/Oレイテンシ情報のデータ構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaIoLatency.ps1 | `public/Get-DbaIoLatency.ps1` | 168-192行目: 出力PSCustomObjectの構造定義 |

**読解のコツ**: Select-DefaultViewの-ExcludePropertyでどのプロパティがデフォルト非表示か確認。

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

処理の起点となるコマンドレット関数を特定。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaIoLatency.ps1 | `public/Get-DbaIoLatency.ps1` | 93-99行目: param()ブロックでパラメータ定義を確認 |

**主要処理フロー**:
1. **159-164行目**: Test-FunctionInterruptで中断チェック
2. **161-165行目**: Connect-DbaInstanceでSQL Server接続
3. **167行目**: Server.Query()でSQLクエリ実行
4. **168-192行目**: 結果オブジェクト構築

#### Step 3: SQLクエリを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaIoLatency.ps1 | `public/Get-DbaIoLatency.ps1` | 102-152行目: I/O統計取得クエリ全体 |

**主要処理フロー**:
- **102-115行目**: 基本カラム選択（database_id, file_id, physical_name等）
- **117-121行目**: ReadLatency計算（CASE式でゼロ除算対応）
- **122-126行目**: WriteLatency計算
- **127-131行目**: 総合Latency計算
- **132-136行目**: AvgBPerRead計算
- **137-141行目**: AvgBPerWrite計算
- **142-148行目**: AvgBPerTransfer計算
- **149-152行目**: INNER JOINでsys.master_filesと結合

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

```
Get-DbaIoLatency
    |
    +-- Test-FunctionInterrupt
    |       +-- 中断チェック
    |
    +-- Connect-DbaInstance (MinimumVersion 9)
    |       +-- SMO Server Object生成
    |
    +-- Server.Query()
    |       +-- sys.dm_io_virtual_file_stats (NULL, NULL)
    |       +-- INNER JOIN sys.master_files
    |
    +-- Select-DefaultView
            +-- ExcludePropertyで非表示プロパティ設定
```

### データフロー図

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

SqlInstance    ------>  Connect-DbaInstance  ----+
                                                 |
SqlCredential  ------>                           |
                                                 v
                        Server.Query()       --> DMV Query
                             |                       |
                             v                       v
                        dm_io_virtual_file_stats + master_files
                             |
                             +-- ReadLatency計算 (IoStallRead/NumberOfReads)
                             +-- WriteLatency計算 (IoStallWrite/NumberOfwrites)
                             +-- Latency計算 (IoStall/(Reads+Writes))
                             +-- AvgBPerRead/Write/Transfer計算
                             |
                             v
                        PSCustomObject
                             |
                             v
                        Select-DefaultView (ExcludeProperty)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaIoLatency.ps1 | `public/Get-DbaIoLatency.ps1` | ソース | I/Oレイテンシ取得の主処理 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続処理 |
