# 画面設計書 133-ネットワークレイテンシ

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるSQL Serverネットワークレイテンシ測定機能の設計仕様を定義する。

### 本画面の処理概要

SQL Serverインスタンスへのクエリ実行時間を測定し、ネットワークレイテンシとクエリ実行時間を分離して分析可能な情報を提供する。

**業務上の目的・背景**：SQL Serverのパフォーマンス問題を診断する際、レスポンス遅延がネットワーク起因かSQL Server処理起因かを切り分ける必要がある。単純なPingテストではSQL Server接続を確立しないため、実際のSQL接続パフォーマンスを測定できない。本機能は、実際にSQL Server接続を確立してクエリを実行し、接続確立時間を含む総合時間とクエリ実行のみの時間を分離して測定する。これにより、ネットワーク遅延の影響を定量的に評価できる。

**画面へのアクセス方法**：PowerShellコンソールから以下のコマンドを実行してアクセスする
- `Test-DbaNetworkLatency -SqlInstance <インスタンス名>`

**主要な操作・処理内容**：
1. 指定されたSQL Serverインスタンスへ接続を確立
2. 指定されたクエリ（デフォルト: SELECT TOP 100 * FROM INFORMATION_SCHEMA.TABLES）を指定回数（デフォルト: 3回）実行
3. 総合実行時間と純粋なクエリ実行時間を測定
4. 平均時間とネットワークオーバーヘッドを計算して出力

**画面遷移**：CLIベースのため画面遷移は存在しない。

**権限による表示制御**：対象SQL Serverインスタンスへの接続権限が必要。指定したクエリを実行する権限も必要。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 375 | Test-DbaNetworkLatency | 主機能 | ネットワークレイテンシのテスト |
| - | Connect-DbaInstance | 補助機能 | SQL Server接続の確立 |

## 画面種別

CLI（コマンドラインインターフェース）

## URL/ルーティング

該当なし（PowerShellコマンドレット）

## 入出力項目

### Test-DbaNetworkLatency

| 項目名 | データ型 | 必須 | 説明 |
|--------|----------|------|------|
| SqlInstance | DbaInstance[] | はい | 対象SQLインスタンス |
| SqlCredential | PSCredential | いいえ | SQL認証用資格情報 |
| Query | string | いいえ | テストに使用するクエリ（デフォルト: SELECT TOP 100 * FROM INFORMATION_SCHEMA.TABLES） |
| Count | int | いいえ | クエリ実行回数（デフォルト: 3） |
| EnableException | switch | いいえ | 例外を直接発生させるかどうか |

## 表示項目

### Test-DbaNetworkLatency 出力（デフォルトビュー）

| 項目名 | データ型 | 説明 |
|--------|----------|------|
| ComputerName | string | コンピュータ名 |
| InstanceName | string | インスタンス名 |
| SqlInstance | string | 完全なSQLインスタンス名 |
| ExecutionCount | int | クエリ実行回数 |
| Total | prettytimespan | 全実行の総合時間（接続+クエリ） |
| Average | prettytimespan | 平均時間 |
| ExecuteOnlyTotal | prettytimespan | クエリ実行のみの総合時間 |
| ExecuteOnlyAverage | prettytimespan | クエリ実行のみの平均時間 |
| NetworkOnlyTotal | prettytimespan | ネットワークオーバーヘッド時間 |

## イベント仕様

### 1-Test-DbaNetworkLatency実行

1. 各SqlInstanceに対して処理を開始
2. System.Diagnostics.Stopwatchで総合時間の計測を開始
3. Connect-DbaInstanceでSQL Server接続を確立
4. 指定回数（Count）だけクエリを実行
5. 初回クエリから最終クエリまでの純粋な実行時間を別途計測
6. 総合時間、平均時間、実行のみ時間、ネットワーク時間を計算
7. prettytimespan形式で結果を出力

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

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

本機能は読み取り専用のSELECTクエリを実行するのみで、データベースの変更は発生しない。

| 操作（イベント） | 対象 | 操作種別 | 概要 |
|----------------|------|---------|------|
| Test-DbaNetworkLatency | INFORMATION_SCHEMA.TABLES | SELECT | システムビューへの読み取りアクセス |

## メッセージ仕様

| メッセージID | 種別 | メッセージ | 発生条件 |
|-------------|------|----------|----------|
| - | Error | Failure | SQL Server接続失敗時 |
| - | Error | Error occurred testing dba network latency: {エラー詳細} | クエリ実行中のエラー |

## 例外処理

| 例外条件 | 処理内容 |
|----------|----------|
| SQL Server接続失敗 | ConnectionErrorカテゴリでStop-Functionを呼び出し、次のインスタンスへ継続 |
| クエリ実行エラー | エラーを記録し、次のインスタンスへ継続 |

## 備考

- 時間はprettytimespan形式（ms、sec等の人間可読形式）で表示される
- TotalとExecuteOnlyTotalの差がネットワークレイテンシと接続確立時間を表す
- デフォルトクエリはINFORMATION_SCHEMA.TABLESを使用し、全SQL Serverバージョンで一貫した結果を提供
- カスタムクエリを使用することで、実際のワークロードに近いレイテンシ測定が可能
- 実行回数を増やすことで、より統計的に信頼性の高い平均値を取得可能

---

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

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

### 推奨読解順序

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

まず、出力されるオブジェクトの構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Test-DbaNetworkLatency.ps1 | `public/Test-DbaNetworkLatency.ps1` | .OUTPUTSセクションで出力プロパティの意味を確認（行54-71） |

**読解のコツ**: prettytimespanは人間が読みやすい時間表示のためのdbatoolsカスタム型で、ミリ秒から適切な単位（ms、sec等）に自動変換される。

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

処理の起点となる関数のパラメータ定義を特定。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Test-DbaNetworkLatency.ps1 | `public/Test-DbaNetworkLatency.ps1` | paramブロックでパラメータ定義を確認（行91-98） |

**主要処理フロー**:
1. **行93**: SqlInstanceは必須パラメータ
2. **行95**: Queryのデフォルト値はINFORMATION_SCHEMA.TABLESへのSELECT
3. **行96**: Countのデフォルト値は3

#### Step 3: メイン処理フローを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Test-DbaNetworkLatency.ps1 | `public/Test-DbaNetworkLatency.ps1` | processブロック内の時間計測ロジック |

**主要処理フロー**:
- **行102**: 総合時間計測用Stopwatch開始
- **行105**: Connect-DbaInstanceで接続確立
- **行110-118**: do-whileループでクエリ繰り返し実行
- **行111-112**: 初回実行時に純粋実行時間計測開始
- **行114**: $server.Query()でクエリ実行
- **行121-130**: 各種時間の計算（総合、平均、実行のみ、ネットワーク）
- **行132-142**: PSCustomObjectで結果を構築
- **行142**: Select-DefaultViewで表示プロパティ設定

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

```
Test-DbaNetworkLatency
    |
    +-- foreach ($instance in $SqlInstance)
            |
            +-- [System.Diagnostics.Stopwatch]::StartNew()
            |       +-- 総合時間計測開始
            |
            +-- Connect-DbaInstance
            |       +-- SQL Server接続確立
            |
            +-- do { $server.Query($query) } while (...)
            |       +-- クエリ繰り返し実行
            |       +-- 純粋実行時間計測
            |
            +-- 時間計算
            |       +-- Total = 総合時間
            |       +-- Average = Total / Count
            |       +-- ExecuteOnlyTotal = 純粋実行時間
            |       +-- ExecuteOnlyAverage = ExecuteOnlyTotal / Count
            |       +-- NetworkOnlyTotal = Total - ExecuteOnlyTotal
            |
            +-- [PSCustomObject] 結果出力
```

### データフロー図

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

SqlInstance ────────▶ Connect-DbaInstance ───────────▶ $server
    |                        |
    v                        v
Query ──────────────▶ $server.Query($query) ─────────▶ クエリ結果
    |                   x Count回                         (破棄)
    v                        |
Count ───────────────────────┘
                             |
                             v
                    ┌──────────────────────┐
                    │   時間計算           │
                    │  ・Total             │
                    │  ・Average           │
                    │  ・ExecuteOnlyTotal  │
                    │  ・ExecuteOnlyAverage│
                    │  ・NetworkOnlyTotal  │
                    └──────────────────────┘
                             |
                             v
                    ┌──────────────────────┐    ┌──────────────────┐
                    │  [PSCustomObject]    │───▶│ レイテンシ測定結果 │
                    │  prettytimespan変換  │    └──────────────────┘
                    └──────────────────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Test-DbaNetworkLatency.ps1 | `public/Test-DbaNetworkLatency.ps1` | ソース | ネットワークレイテンシ測定メインコマンド |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続確立 |
