# 画面設計書 83-レプリケーションレイテンシ

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるレプリケーションレイテンシ測定機能の設計仕様を定義する。トレーサートークンを使用して、トランザクションレプリケーションにおけるパブリッシャーからサブスクライバーへのデータ伝播遅延を計測する。

### 本画面の処理概要

本機能は、トランザクションレプリケーション環境においてレイテンシ（遅延時間）を測定し、レプリケーションパフォーマンスの監視とトラブルシューティングを支援するコマンドラインインターフェースを提供する。

**業務上の目的・背景**：トランザクションレプリケーション環境では、パブリッシャーでのデータ変更がサブスクライバーに反映されるまでの時間が重要なSLA指標となる。本機能は、トレーサートークン（追跡用のマーカー）をパブリケーションのトランザクションログに挿入し、それがディストリビューターを経由してサブスクライバーに到達するまでの時間を測定することで、リアルタイムのレイテンシデータを取得する。これにより、レプリケーション遅延の検出、構成変更後のパフォーマンス検証、ベースラインメトリクスの確立が可能になる。

**画面へのアクセス方法**：PowerShellコンソールまたはスクリプトから以下のコマンドを実行してアクセスする：
- `Test-DbaReplLatency -SqlInstance <パブリッシャー名>`

**主要な操作・処理内容**：
1. トレーサートークンをパブリケーションのトランザクションログに挿入
2. パブリッシャーからディストリビューターへのレイテンシを測定
3. ディストリビューターから各サブスクライバーへのレイテンシを測定
4. トータルレイテンシ（エンドツーエンド）を計算
5. オプションでトレーサートークン履歴を保持または自動クリーンアップ
6. 既存トークンの履歴表示（DisplayTokenHistory）

**画面遷移**：
- 入力元：トランザクションレプリケーション環境が構築済みであること
- 関連：`Get-DbaReplPublication`でパブリケーション情報を事前確認

**権限による表示制御**：sysadmin権限が必要。ディストリビューターへの接続権限も必要。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 457 | Test-DbaReplLatency | 主機能 | レプリケーションレイテンシのテスト |
| 446 | Get-DbaReplPublication | 遷移元機能 | パブリケーション情報の取得 |

## 画面種別

コマンドラインインターフェース（CLI） / 診断・テスト

## URL/ルーティング

PowerShellコマンド呼び出し：
- `Test-DbaReplLatency -SqlInstance <パブリッシャー名>`
- `Test-DbaReplLatency -SqlInstance <パブリッシャー名> -Database <DB名>`
- `Test-DbaReplLatency -SqlInstance <パブリッシャー名> -PublicationName <パブリケーション名>`
- `Test-DbaReplLatency -SqlInstance <パブリッシャー名> -RetainToken -DisplayTokenHistory`

## 入出力項目

### Test-DbaReplLatency 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | はい | パブリッシャーSQLインスタンス |
| Database | object[] | いいえ | 対象データベース |
| SqlCredential | PSCredential | いいえ | 認証情報 |
| PublicationName | object[] | いいえ | 対象パブリケーション名 |
| TimeToLive | int | いいえ | タイムアウト秒数 |
| RetainToken | switch | いいえ | トークン保持フラグ |
| DisplayTokenHistory | switch | いいえ | 履歴表示フラグ |
| EnableException | switch | いいえ | 例外処理の有効化 |

## 表示項目

### Test-DbaReplLatency 出力オブジェクト

| プロパティ名 | 型 | 説明 |
|-------------|-----|------|
| ComputerName | string | パブリッシャーコンピュータ名 |
| InstanceName | string | パブリッシャーインスタンス名 |
| SqlInstance | string | 完全パブリッシャーインスタンス名 |
| TokenID | int | トレーサートークンID |
| TokenCreateDate | datetime | トークン作成日時 |
| PublicationServer | string | パブリッシャーサーバー名 |
| PublicationDB | string | パブリケーションDB名 |
| PublicationName | string | パブリケーション名 |
| PublicationType | string | パブリケーションタイプ |
| DistributionServer | string | ディストリビューターサーバー名 |
| DistributionDB | string | ディストリビューションDB名 |
| SubscriberServer | string | サブスクライバーサーバー名 |
| SubscriberDB | string | サブスクライバーDB名 |
| PublisherToDistributorLatency | timespan/DBNull | パブリッシャー→ディストリビューター遅延 |
| DistributorToSubscriberLatency | timespan/DBNull | ディストリビューター→サブスクライバー遅延 |
| TotalLatency | timespan/DBNull | トータルレイテンシ |

## イベント仕様

### 1-トレーサートークン挿入

1. パブリッシャーに接続（Connect-DbaInstance、MinimumVersion 9）
2. Get-DbaReplPublicationでトランザクションパブリケーション取得
3. 各パブリケーションに対してTransPublicationオブジェクト作成
4. LoadProperties()でプロパティ読み込み
5. PostTracerToken()でトレーサートークンを挿入

### 2-レイテンシ測定

1. ReplicationServerオブジェクトを作成
2. ディストリビューターサーバー名とDB名を取得
3. ディストリビューターに接続
4. PublicationMonitorオブジェクトを作成
5. EnumTracerTokens()でトークン一覧を取得
6. EnumTracerTokenHistory()でレイテンシ情報を取得
7. subscriber_latencyがDBNullでなくなるまで待機（TimeToLive制限）
8. 結果をPSCustomObjectで出力

### 3-トークンクリーンアップ

1. RetainTokenが指定されていない場合
2. CleanUpTracerTokenHistory()でトークン履歴を削除

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| PostTracerToken() | MStracer_tokens | INSERT | トレーサートークンの挿入 |
| EnumTracerTokenHistory() | MStracer_history | SELECT | トークン履歴の取得 |
| CleanUpTracerTokenHistory() | MStracer_tokens, MStracer_history | DELETE | トークン履歴の削除 |

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

#### MStracer_tokens（ディストリビューションDB）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | tracer_id | 自動採番 | トレーサートークンID |
| INSERT | publication_id | パブリケーションID | 対象パブリケーション |
| INSERT | publisher_commit | トークン挿入日時 | 自動設定 |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|---------------|---------|
| MSG001 | エラー | LoadProperties() failed. The publication does not exist. | パブリケーション未存在時 |
| MSG002 | 警告 | TimeToLive has been reached for token: {tracerTokenId} | タイムアウト到達時 |
| MSG003 | エラー | Failure | 接続エラー時 |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 接続エラー | Stop-Functionでエラーメッセージを表示し、次のインスタンスに継続 |
| パブリケーション未存在 | Stop-Functionで警告を表示し、次のパブリケーションに継続 |
| タイムアウト | 警告メッセージを表示し、次のトークンに継続 |
| ディストリビューター接続エラー | Stop-Functionでエラーを表示し処理を停止 |

## 備考

- SQL Server 2005以降が必要（MinimumVersion 9）
- トランザクションレプリケーションのみサポート（マージレプリケーションは対象外）
- SQL Server Management Studioのインストールが必要（レプリケーションRMOライブラリ依存）
- トレーサートークンは1時間有効で自動期限切れ
- DisplayTokenHistoryを使用すると、現在のテストトークンだけでなく全履歴を表示
- レイテンシ値がDBNullの場合は、まだトークンが到達していないことを示す

---

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

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

### 推奨読解順序

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

出力はPSCustomObjectで、レイテンシ情報を含む。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Test-DbaReplLatency.ps1 | `public/Test-DbaReplLatency.ps1` | 出力オブジェクトの構造（63-85行目）を確認 |

**読解のコツ**: .OUTPUTSセクションで各プロパティの意味と型を確認。特にtimespan/DBNull型の扱いに注意。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Test-DbaReplLatency.ps1 | `public/Test-DbaReplLatency.ps1` | param()ブロック（101-112行目）で入力パラメータを確認 |

**主要処理フロー**:
1. **113-115行目**: Add-ReplicationLibraryでRMOライブラリロード
2. **121-125行目**: Connect-DbaInstance（MinimumVersion 9）
3. **127-131行目**: Get-DbaReplPublicationでトランザクションパブリケーション取得
4. **137-152行目**: TransPublicationオブジェクト作成とPostTracerToken()実行

#### Step 3: レイテンシ測定処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Test-DbaReplLatency.ps1 | `public/Test-DbaReplLatency.ps1` | PublicationMonitorの使用（174-190行目） |

**主要処理フロー**:
- **159-164行目**: ReplicationServerからディストリビューター情報取得
- **168-172行目**: ディストリビューターに接続
- **176-184行目**: PublicationMonitorオブジェクト作成とLoadProperties()
- **192-196行目**: EnumTracerTokens()でトークン一覧取得
- **199-218行目**: レイテンシ取得の待機ループ（TimeToLive制限）
- **229-246行目**: PSCustomObject出力

#### Step 4: トークンクリーンアップを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Test-DbaReplLatency.ps1 | `public/Test-DbaReplLatency.ps1` | CleanUpTracerTokenHistory呼び出し（249-251行目） |

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

```
Test-DbaReplLatency
    │
    ├─ Add-ReplicationLibrary (内部関数)
    │      └─ RMOライブラリのロード
    │
    ├─ Connect-DbaInstance (パブリッシャー)
    │      └─ SMOサーバーオブジェクト取得
    │
    ├─ Get-DbaReplPublication (Type="Transactional")
    │      └─ トランザクションパブリケーション取得
    │
    ├─ TransPublication.PostTracerToken()
    │      └─ MStracer_tokensへのINSERT
    │
    ├─ ReplicationServer
    │      └─ ディストリビューター情報取得
    │
    ├─ Connect-DbaInstance (ディストリビューター)
    │      └─ ディストリビューター接続
    │
    ├─ PublicationMonitor.EnumTracerTokens()
    │      └─ トークン一覧取得
    │
    ├─ PublicationMonitor.EnumTracerTokenHistory()
    │      └─ レイテンシ情報取得
    │
    └─ PublicationMonitor.CleanUpTracerTokenHistory()
           └─ トークン履歴削除（RetainToken未指定時）
```

### データフロー図

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

SqlInstance ───────▶ Connect-DbaInstance (Publisher) ──▶ SMO Server
                              │
                              ▼
                     TransPublication.PostTracerToken()
                              │
                              ▼ (トークンID取得)

DistributionServer ◀─ ReplicationServer ─────────────▶ Distributor Info
                              │
                              ▼
                     Connect-DbaInstance (Distributor)
                              │
                              ▼
                     PublicationMonitor.EnumTracerTokenHistory()
                              │
                              ▼
         ┌──────────────────────────────────────────────┐
         │  PublisherToDistributorLatency              │
         │  DistributorToSubscriberLatency             │──▶ PSCustomObject
         │  TotalLatency                               │
         └──────────────────────────────────────────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Test-DbaReplLatency.ps1 | `public/Test-DbaReplLatency.ps1` | ソース | レイテンシテスト実行 |
| Get-DbaReplPublication.ps1 | `public/Get-DbaReplPublication.ps1` | 依存 | パブリケーション情報取得 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | 依存 | SQL Server接続 |
