# 機能設計書 655-Test-DbaDiskSpeed

## 概要

本ドキュメントは、dbatools PowerShellモジュールの `Test-DbaDiskSpeed` 関数の機能設計を記述するものである。本機能はSQL ServerのDMV（動的管理ビュー）を使用してデータベースファイルのI/Oパフォーマンスを分析し、ストレージボトルネックを特定するコマンドレットである。

### 本機能の処理概要

**業務上の目的・背景**：
SQL Serverのパフォーマンス問題の多くはストレージI/Oに起因する。本機能は `sys.dm_io_virtual_file_stats` DMVを照会して、読み取り/書き込みのレイテンシ、スループット、全体的なI/Oパフォーマンスを測定する。平均ストール時間に基づいて「Very Good」から「Serious I/O Bottleneck」までのパフォーマンス評価を返し、ストレージの問題を迅速に特定できる。

**機能の利用シーン**：
- クエリの遅延問題のトラブルシューティング
- ストレージアップグレードの効果検証
- プロアクティブなパフォーマンス監視
- データベースファイル配置の最適化検討

**主要な処理内容**：
1. SQL Serverインスタンスへの接続
2. sys.dm_io_virtual_file_stats DMVからI/O統計情報の取得
3. 集計レベルに応じた結果の集約（File/Database/Disk）
4. 読み取り/書き込みストール時間に基づくパフォーマンス評価
5. 結果オブジェクトの生成と出力

**関連システム・外部連携**：
- SQL Server DMV (sys.dm_io_virtual_file_stats)
- sys.master_files システムカタログビュー
- Connect-DbaInstance コマンドレットによるSQL Server接続

**権限による制御**：
- VIEW SERVER STATE 権限が必要
- または sysadmin ロールのメンバーシップ

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | CLI (PowerShell) | 主画面 | コマンドライン実行によるI/O分析 |

## 機能種別

データ取得処理（SELECT） / パフォーマンス診断処理

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstance[] | Yes | 対象SQL Serverインスタンス | 必須、パイプライン入力可 |
| SqlCredential | PSCredential | No | SQL Server接続用資格情報 | - |
| Database | object[] | No | 対象データベース名 | - |
| ExcludeDatabase | object[] | No | 除外データベース名 | - |
| AggregateBy | string | No | 集計レベル（デフォルト: File） | File, Database, Diskのいずれか |
| EnableException | switch | No | 例外処理の有効化 | - |

### 入力データソース

- PowerShellコマンドラインからのパラメータ入力
- SQL Server DMVからのI/O統計情報

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全修飾インスタンス名 |
| Database | string | データベース名（File/Database集計時） |
| SizeGB | decimal | ファイルサイズ（GB）（File集計時のみ） |
| FileName | string | ファイル名（File集計時のみ） |
| FileID | int | ファイルID（File集計時のみ） |
| FileType | string | ファイルタイプ（Log/Data）（File集計時のみ） |
| DiskLocation | string | ディスク位置（Disk集計時） |
| Reads | long | 読み取り操作数 |
| AverageReadStall | int | 平均読み取りストール（ミリ秒） |
| ReadPerformance | string | 読み取りパフォーマンス評価 |
| Writes | long | 書き込み操作数 |
| AverageWriteStall | int | 平均書き込みストール（ミリ秒） |
| WritePerformance | string | 書き込みパフォーマンス評価 |
| Avg Overall Latency | int | 平均全体レイテンシ |
| Avg Bytes/Read | long | 読み取りあたり平均バイト数 |
| Avg Bytes/Write | long | 書き込みあたり平均バイト数 |
| Avg Bytes/Transfer | long | 転送あたり平均バイト数 |

### 出力先

PowerShellパイプライン（集計レベルに応じたオブジェクト）

## 処理フロー

### 処理シーケンス

```
1. 初期化処理（beginブロック）
   └─ ベースSQLクエリの構築
   └─ AggregateByに応じたSQLクエリの調整
   └─ Database/ExcludeDatabaseフィルタの適用

2. メイン処理（processブロック）
   └─ 各SQL Serverインスタンスに対して処理
       └─ Connect-DbaInstance で接続（MinimumVersion 9）
       └─ HostPlatformに応じたSQL調整（Windows/Linux）
       └─ クエリ実行と結果出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[ベースSQLクエリ構築]
    B --> C{AggregateBy?}
    C -->|File| D[File用SQL生成]
    C -->|Database| E[Database用SQL生成]
    C -->|Disk| F[Disk用SQL生成]
    D --> G{Database/ExcludeDB指定?}
    E --> G
    F --> G
    G -->|Yes| H[WHERE句追加]
    G -->|No| I[各インスタンスをループ]
    H --> I
    I --> J[Connect-DbaInstance]
    J --> K{接続成功?}
    K -->|No| L[エラー: Continue]
    K -->|Yes| M{HostPlatform?}
    M -->|Linux| N[Linux用SQL調整]
    M -->|Windows| O[Windows用SQL調整]
    N --> P[クエリ実行]
    O --> P
    P --> Q[結果出力]
    Q --> R{次のインスタンス?}
    R -->|Yes| I
    R -->|No| S[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | パフォーマンス評価 Very Good | ストール < 10ms | 読み取り/書き込みストール評価時 |
| BR-002 | パフォーマンス評価 OK | ストール 10-20ms | 読み取り/書き込みストール評価時 |
| BR-003 | パフォーマンス評価 Slow | ストール 20-50ms | 読み取り/書き込みストール評価時 |
| BR-004 | パフォーマンス評価 Serious Bottleneck | ストール >= 50ms | 読み取り/書き込みストール評価時 |
| BR-005 | 最小バージョン要件 | SQL Server 2005以上 | インスタンス接続時 |

### 計算ロジック

- 平均読み取りストール: `io_stall_read_ms / num_of_reads`
- 平均書き込みストール: `io_stall_write_ms / num_of_writes`
- 平均全体レイテンシ: `io_stall / (num_of_reads + num_of_writes)`
- 読み取りあたりバイト: `num_of_bytes_read / num_of_reads`
- 書き込みあたりバイト: `num_of_bytes_written / num_of_writes`
- 転送あたりバイト: `(num_of_bytes_read + num_of_bytes_written) / (num_of_reads + num_of_writes)`

## データベース操作仕様

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| I/O統計取得 | sys.dm_io_virtual_file_stats | SELECT | ファイルI/O統計取得 |
| ファイル情報取得 | sys.master_files | SELECT | ファイルメタデータ取得 |

### テーブル別操作詳細

#### sys.dm_io_virtual_file_stats

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | database_id, file_id, num_of_reads, io_stall_read_ms, num_of_writes, io_stall_write_ms, num_of_bytes_read, num_of_bytes_written, io_stall, size_on_disk_bytes | 全ファイルを取得 | DMV関数呼び出し |

#### sys.master_files

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | database_id, file_id, physical_name | dm_io_virtual_file_stats と結合 | ファイルパス取得用 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 接続エラー | SQL Serverへの接続失敗 | Stop-Function with -Continue |
| - | バージョンエラー | SQL Server 2005未満 | MinimumVersion 9 で自動チェック |

### リトライ仕様

自動リトライは実装されていない。

## トランザクション仕様

読み取り専用処理のため、トランザクション管理は不要。

## パフォーマンス要件

- DMVクエリは通常即座に完了
- 多数のデータベース/ファイルがある場合、結果セットが大きくなる可能性
- I/O統計はSQL Server起動時からの累積値

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

- VIEW SERVER STATE 権限が必要
- SqlCredentialパラメータによるセキュアな資格情報の受け渡し
- 読み取り専用操作のためデータ変更リスクなし

## 備考

- 統計はSQL Server起動時からの累積値であることに注意
- Linux環境とWindows環境でパス抽出のSQL構文が異なる
- 結果は（読み取り数 + 書き込み数）の降順でソート

---

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

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

### 推奨読解順序

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

SQLクエリの構造と出力カラムを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Test-DbaDiskSpeed.ps1 | `public/Test-DbaDiskSpeed.ps1` | 145-190行目: ベースSELECTリスト |

**読解のコツ**: SQLクエリ内のコメント（--FILE-ALL, --DATABASE-SELECT等）は実行時に条件に応じてアンコメントされる。CASE文でパフォーマンス評価を行っている。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Test-DbaDiskSpeed.ps1 | `public/Test-DbaDiskSpeed.ps1` | 128-138行目: パラメータ定義 |
| 2-2 | Test-DbaDiskSpeed.ps1 | `public/Test-DbaDiskSpeed.ps1` | 140-236行目: beginブロック |

**主要処理フロー**:
1. **145-190行目**: $selectList でベースSQLを定義
2. **192-223行目**: AggregateBy に応じたSQLクエリ構築
3. **225-233行目**: Database/ExcludeDatabase フィルタ適用

#### Step 3: 集計レベル別SQL生成を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Test-DbaDiskSpeed.ps1 | `public/Test-DbaDiskSpeed.ps1` | 192-197行目: File集計のSQL |
| 3-2 | Test-DbaDiskSpeed.ps1 | `public/Test-DbaDiskSpeed.ps1` | 199-223行目: Database/Disk集計のSQL |

**主要処理フロー**:
- **193-197行目**: File集計 - シンプルなJOIN
- **199-222行目**: Database/Disk集計 - サブクエリでのGROUP BY

#### Step 4: 実行時のSQL調整を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Test-DbaDiskSpeed.ps1 | `public/Test-DbaDiskSpeed.ps1` | 246-272行目: HostPlatformに応じたSQL調整 |

**主要処理フロー**:
- **249-257行目**: File集計時のWindows/Linux切り替え
- **259-271行目**: Database/Disk集計時のWindows/Linux切り替え
- **253-256行目**: コメントを置換してSQL有効化（.replace("--FILE-LINUX", "")等）

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

```
Test-DbaDiskSpeed
    │
    ├─ begin ブロック
    │      ├─ $selectList（ベースSELECT定義）
    │      ├─ AggregateBy分岐
    │      │      ├─ File → 直接クエリ
    │      │      └─ Database/Disk → サブクエリ
    │      └─ WHERE句追加（Database/ExcludeDatabase）
    │
    └─ process ブロック
           ├─ Connect-DbaInstance -MinimumVersion 9
           │
           ├─ HostPlatform判定
           │      ├─ Linux → --LINUX コメント解除
           │      └─ Windows → --WINDOWS コメント解除
           │
           ├─ AggregateBy別追加調整
           │      ├─ File → --DATABASE-SELECT, --FILE-ALL等
           │      └─ Database/Disk → --DATABASE-OR-DISK等
           │
           └─ Server.Query($sqlToRun)
                  └─ 結果出力
```

### データフロー図

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

SqlInstance ────┐
                ├──▶ Connect-DbaInstance
SqlCredential ──┤         │
                │         ▼
Database ───────┤    SQL生成
                │    (AggregateBy依存)
ExcludeDatabase ┤         │
                │         ▼
AggregateBy ────┘    HostPlatform判定
                          │
                    ┌─────┴─────┐
                    │           │
                    ▼           ▼
                 Windows     Linux
                    │           │
                    └─────┬─────┘
                          │
                          ▼
                 sys.dm_io_virtual_file_stats
                          +
                    sys.master_files
                          │
                          ▼
                    パフォーマンス評価
                    (CASE文でVery Good〜Serious)
                          │
                          ▼
                    ─────────────────────────▶ PSCustomObject
                                               (File/DB/Disk単位)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Test-DbaDiskSpeed.ps1 | `public/Test-DbaDiskSpeed.ps1` | ソース | メイン機能実装 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続処理 |
