# 機能設計書 375-Test-DbaNetworkLatency

## 概要

本ドキュメントは、dbatools PowerShellモジュールのTest-DbaNetworkLatencyコマンドの機能設計を定義する。このコマンドはSQL Serverへのクエリ実行時間を測定し、ネットワーク遅延と接続オーバーヘッドを分析する機能を提供する。

### 本機能の処理概要

**業務上の目的・背景**：SQL Serverのパフォーマンス問題の原因特定において、ネットワーク遅延と実際のクエリ実行時間を区別することは重要である。単純なpingテストでは、SQL Server接続の確立とクエリ実行にかかる実際の時間を測定できない。本コマンドは、接続確立からクエリ結果の返却までの全体時間と、純粋なクエリ実行時間を分離して測定することで、問題がネットワークにあるのかSQL Server側にあるのかを特定する。

**機能の利用シーン**：
- SQL Server接続のパフォーマンス診断
- ネットワーク遅延とサーバー処理時間の切り分け
- 複数サーバー間のレスポンス時間比較
- 断続的なネットワーク問題の調査（複数回実行による平均化）

**主要な処理内容**：
1. SQL Serverへの接続確立（Connect-DbaInstance）
2. 指定回数のクエリ実行とStopwatchによる時間測定
3. 全体時間、クエリ実行のみ時間、ネットワークオーバーヘッドの算出
4. 人間が読みやすい形式での結果出力

**関連システム・外部連携**：
- SQL Server（SMO経由での接続とクエリ実行）
- System.Diagnostics.Stopwatch（時間計測）

**権限による制御**：SQL Serverへの接続権限が必要。SqlCredentialパラメータによる代替資格情報の指定が可能。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | コマンドライン/PowerShell | 主画面 | コマンド実行とパラメータ指定 |

## 機能種別

診断・検証 / パフォーマンス計測

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstance[] | Yes | 対象SQL Serverインスタンス（パイプライン入力可） | - |
| SqlCredential | PSCredential | No | SQL Server接続用の代替資格情報 | - |
| Query | string | No | 実行するSQLクエリ | デフォルト: "SELECT TOP 100 * FROM INFORMATION_SCHEMA.TABLES" |
| Count | int | No | クエリ実行回数 | デフォルト: 3 |
| EnableException | switch | No | 例外処理の有効化 | - |

### 入力データソース

- SqlInstanceパラメータ: ユーザー指定またはパイプライン入力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| Count | int | 実行回数（Countパラメータと同じ） |
| Total | prettytimespan | 全実行の合計時間（接続とネットワークオーバーヘッド含む） |
| Avg | prettytimespan | 実行あたりの平均時間 |
| ExecuteOnlyTotal | prettytimespan | クエリ実行のみの合計時間 |
| ExecuteOnlyAvg | prettytimespan | クエリ実行のみの平均時間 |
| NetworkOnlyTotal | prettytimespan | ネットワークオーバーヘッドの合計時間 |

### 出力先

PowerShellパイプライン（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. Process ブロック: メインの処理ループ
   └─ 各インスタンスに対する処理
      └─ 全体時間計測用Stopwatch開始
      └─ Connect-DbaInstanceで接続確立
      └─ 指定回数のクエリ実行ループ
         └─ 1回目でクエリ実行時間計測用Stopwatch開始
         └─ $server.Query()でクエリ実行
         └─ 最終回でクエリ実行時間を記録
      └─ 全体時間を記録
      └─ 平均時間の算出
      └─ ネットワークオーバーヘッドの算出
      └─ 結果オブジェクトの出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[インスタンスループ開始]
    B --> C[全体Stopwatch開始]
    C --> D[Connect-DbaInstance]
    D --> E{接続成功?}
    E -->|No| F[Stop-Function]
    E -->|Yes| G[currentCount=0]
    G --> H{currentCount < count?}
    H -->|Yes| I[currentCount++]
    I --> J{1回目?}
    J -->|Yes| K[クエリ実行Stopwatch開始]
    J -->|No| L[$server.Query実行]
    K --> L
    L --> M{最終回?}
    M -->|Yes| N[クエリ実行時間記録]
    M -->|No| H
    N --> H
    H -->|No| O[全体時間記録]
    O --> P[平均時間算出]
    P --> Q[ネットワークオーバーヘッド算出]
    Q --> R[結果オブジェクト出力]
    R --> S{次のインスタンス?}
    F --> S
    S -->|Yes| B
    S -->|No| T[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | デフォルトクエリ | Query未指定時は"SELECT TOP 100 * FROM INFORMATION_SCHEMA.TABLES"を使用 | Query未指定時 |
| BR-002 | デフォルト実行回数 | Count未指定時は3回実行 | Count未指定時 |
| BR-003 | 単一回実行時の平均 | Count=1の場合、averageWarmはtotalWarmと同じ | Count=1 |

### 計算ロジック

- Total（全体時間）: 接続確立から最終クエリ完了までの時間
- Average（平均時間）: Total / Count
- ExecuteOnlyTotal（クエリ実行のみ）: 1回目のクエリ開始から最終回完了までの時間
- ExecuteOnlyAverage: ExecuteOnlyTotal / Count（Count=1の場合は同値）
- NetworkOnlyTotal: Total - ExecuteOnlyTotal

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 計測クエリ | INFORMATION_SCHEMA.TABLES | SELECT | デフォルトクエリ（読み取りのみ） |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ConnectionError | SQL Server接続失敗 | Stop-Functionで継続、対象インスタンスをスキップ |
| - | QueryError | クエリ実行エラー | Stop-Functionで継続 |

### リトライ仕様

リトライ機構は実装されていない。

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

トランザクション管理は行わない（SELECTクエリのみ）。

## パフォーマンス要件

- 測定対象の性能に依存
- Countパラメータで測定回数を調整可能

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

- SqlCredentialパラメータによる代替資格情報のサポート
- Windows認証、SQL Server認証、Active Directory認証をサポート
- MFAが必要な場合はConnect-DbaInstanceの使用を推奨

## 備考

- TotalとExecuteOnlyTotalの差がネットワーク遅延と接続確立時間を表す
- 時間値はprettytimespanオブジェクトとして返され、人間が読みやすい形式（ms, secなど）で表示される

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Test-DbaNetworkLatency.ps1 | `public/Test-DbaNetworkLatency.ps1` | **132-142行目**: 出力PSCustomObjectの構造定義 |

**読解のコツ**: prettytimespanはミリ秒から作成され、表示時に自動的に適切な単位（ms, sec等）に変換される。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Test-DbaNetworkLatency.ps1 | `public/Test-DbaNetworkLatency.ps1` | **89-98行目**: パラメータ定義 |

**主要処理フロー**:
1. **89行目**: CmdletBinding属性
2. **90行目**: OutputTypeの宣言
3. **92-93行目**: SqlInstanceパラメータ（Mandatory、ValueFromPipeline）
4. **95行目**: Queryパラメータ（デフォルト値あり）
5. **96行目**: Countパラメータ（デフォルト: 3）

#### Step 3: Processブロック - 時間計測処理

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Test-DbaNetworkLatency.ps1 | `public/Test-DbaNetworkLatency.ps1` | **99-147行目**: メイン処理 |

**主要処理フロー**:
- **102行目**: 全体時間計測用Stopwatch開始
- **104-108行目**: Connect-DbaInstanceでSQL Server接続
- **110-119行目**: クエリ実行ループ
- **111-113行目**: 1回目でクエリ実行Stopwatch開始
- **114行目**: $server.Query()でクエリ実行
- **115-117行目**: 最終回で実行時間記録
- **121-130行目**: 時間計算
- **132-142行目**: 結果オブジェクト構築とSelect-DefaultView

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

```
Test-DbaNetworkLatency
    │
    ├─ [System.Diagnostics.Stopwatch]::StartNew()
    │      └─ 全体時間計測開始
    │
    ├─ Connect-DbaInstance
    │      └─ SQL Server接続確立
    │
    ├─ $server.Query()
    │      └─ クエリ実行（Count回ループ）
    │
    ├─ [prettytimespan]::FromMilliseconds()
    │      └─ 時間値の変換
    │
    └─ Select-DefaultView
           └─ 出力プロパティ制御
```

### データフロー図

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

SqlInstance ──────────────▶ Stopwatch開始（全体）
                                   │
                                   ▼
                           Connect-DbaInstance ──────────▶ 接続確立
                                   │
                                   ▼
Query, Count ─────────────▶ Stopwatch開始（クエリ）
                                   │
                                   ▼
                           $server.Query() x Count回
                                   │
                                   ▼
                           時間計算 ──────────────────▶ PSCustomObject出力
                           (Total, Avg, ExecuteOnly,
                            NetworkOnly)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Test-DbaNetworkLatency.ps1 | `public/Test-DbaNetworkLatency.ps1` | ソース | メイン機能実装 |
