# 機能設計書 457-Test-DbaReplLatency

## 概要

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

### 本機能の処理概要

**業務上の目的・背景**：トランザクションレプリケーション環境において、データ変更がサブスクライバーに到達するまでの遅延時間は、ビジネスクリティカルな情報のリアルタイム性を保証するために重要な指標である。本関数は、トレーサートークンを使用してエンドツーエンドのレプリケーション遅延を測定し、レプリケーションパフォーマンスのベースライン確立やボトルネック特定を支援する。

**機能の利用シーン**：
- レプリケーション性能の定期監視時
- 構成変更後の性能検証時
- レプリケーション遅延のトラブルシューティング時
- SLAコンプライアンスの検証時

**主要な処理内容**：
1. パブリッシャーへの接続とTransPublicationオブジェクト作成
2. トレーサートークンの発行（PostTracerToken）
3. ディストリビューターへの接続とPublicationMonitorオブジェクト作成
4. トレーサートークン履歴の取得と遅延時間計算
5. 結果オブジェクトの出力（オプションでトークンのクリーンアップ）

**関連システム・外部連携**：SQL Server Replication Management Objects (RMO)、ディストリビューター、トランザクションログ

**権限による制御**：パブリッシャーおよびディストリビューターへの接続権限が必要（通常sysadmin）

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| N/A | SQL Server Management Studio - レプリケーションモニター - トレーサートークン | 参照画面 | トレーサートークン監視機能に相当 |

## 機能種別

診断・監視 / レプリケーション性能測定

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | パブリッシャーSQL Serverインスタンス | パイプライン入力対応 |
| Database | Object[] | No | テスト対象データベース | ワイルドカード対応 |
| SqlCredential | PSCredential | No | SQL Server認証用資格情報 | 有効な認証情報 |
| PublicationName | Object[] | No | テスト対象パブリケーション名 | ワイルドカード対応 |
| TimeToLive | Int | No | トレーサートークンの最大待機時間（秒） | 正の整数 |
| RetainToken | Switch | No | テスト後にトレーサートークンを保持 | なし |
| DisplayTokenHistory | Switch | No | 全てのトレーサートークン履歴を表示 | なし |
| EnableException | Switch | No | 例外を有効化 | なし |

### 入力データソース

- パラメータ入力
- SQL ServerインスタンスのレプリケーションメタデータGT

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | String | パブリッシャーホストのコンピュータ名 |
| InstanceName | String | パブリッシャーインスタンス名 |
| SqlInstance | String | パブリッシャーフルインスタンス名 |
| TokenID | Int | トレーサートークンの一意識別子 |
| TokenCreateDate | DateTime | トレーサートークンの作成日時 |
| PublicationServer | String | パブリッシャーサーバー名 |
| PublicationDB | String | パブリケーションデータベース名 |
| PublicationName | String | パブリケーション名 |
| PublicationType | String | パブリケーションタイプ |
| DistributionServer | String | ディストリビューターサーバー名 |
| DistributionDB | String | ディストリビューションデータベース名 |
| SubscriberServer | String | サブスクライバーサーバー名 |
| SubscriberDB | String | サブスクライバーデータベース名 |
| PublisherToDistributorLatency | TimeSpan/DBNull | パブリッシャーからディストリビューターへの遅延 |
| DistributorToSubscriberLatency | TimeSpan/DBNull | ディストリビューターからサブスクライバーへの遅延 |
| TotalLatency | TimeSpan/DBNull | エンドツーエンドの合計遅延 |

### 出力先

パイプラインに遅延測定結果オブジェクトを出力

## 処理フロー

### 処理シーケンス

```
1. パブリッシャーへの接続
   └─ Connect-DbaInstance（最小バージョン9 = SQL 2005）
2. トランザクションパブリケーション取得
   └─ Get-DbaReplPublication（Type = Transactional）
3. 各パブリケーションへのトレーサートークン発行
   ├─ TransPublicationオブジェクト作成
   ├─ LoadProperties()で存在確認
   └─ PostTracerToken()でトークン発行
4. ディストリビューター情報取得
   ├─ ReplicationServerオブジェクト作成
   └─ DistributionServer/DistributionDatabase取得
5. ディストリビューターへの接続
   └─ Connect-DbaInstance
6. 各パブリケーションの遅延測定
   ├─ PublicationMonitorオブジェクト作成
   ├─ EnumTracerTokens()でトークン一覧取得
   ├─ EnumTracerTokenHistory()で遅延情報取得
   ├─ TimeToLive指定時は待機ループ実行
   └─ TotalLatency計算（distributor_latency + subscriber_latency）
7. 結果出力とクリーンアップ
   ├─ PSCustomObject作成
   └─ RetainToken未指定時はCleanUpTracerTokenHistory()
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[Connect-DbaInstance パブリッシャー]
    B --> C[Get-DbaReplPublication Transactional]
    C --> D{PublicationNameフィルタ?}
    D -->|Yes| E[パブリケーションフィルタ]
    D -->|No| F[foreach publication]
    E --> F
    F --> G[TransPublication作成]
    G --> H[LoadProperties]
    H --> I{成功?}
    I -->|No| J[エラー継続]
    I -->|Yes| K[PostTracerToken]
    K --> L[ReplicationServer作成]
    L --> M[DistributionServer取得]
    M --> N[Connect-DbaInstance ディストリビューター]
    N --> O[foreach publication]
    O --> P[PublicationMonitor作成]
    P --> Q[LoadProperties]
    Q --> R[EnumTracerTokens]
    R --> S{DisplayTokenHistory?}
    S -->|No| T[最新トークンのみ]
    S -->|Yes| U[全トークン履歴]
    T --> V[foreach token]
    U --> V
    V --> W[EnumTracerTokenHistory]
    W --> X{subscriber_latency = DBNull?}
    X -->|Yes & TimeToLive設定| Y[待機ループ]
    X -->|No or TimeToLive超過| Z[TotalLatency計算]
    Y --> X
    Z --> AA[PSCustomObject作成]
    AA --> AB{RetainToken?}
    AB -->|No| AC[CleanUpTracerTokenHistory]
    AB -->|Yes| AD[次のトークン]
    AC --> AD
    AD --> V
    V -->|完了| AE[次のパブリケーション]
    AE --> O
    O -->|完了| AF[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | Transactionalのみ対応 | トレーサートークンはTransactionalレプリケーションでのみ使用可能 | 常時適用 |
| BR-002 | TimeToLive待機 | 指定時間内にサブスクライバーに到達しない場合はタイムアウト | TimeToLive指定時 |
| BR-003 | トークン自動クリーンアップ | -RetainToken未指定時はテスト後にトークンを削除 | 既定動作 |
| BR-004 | 最小バージョンSQL 2005 | SQL Server 2005以上が必要 | 常時適用 |

### 計算ロジック

TotalLatencyの計算:
- `TotalLatency = PublisherToDistributorLatency + DistributorToSubscriberLatency`
- いずれかがDBNullの場合、TotalLatencyもDBNull

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| トレーサートークン発行 | MStracer_tokens | INSERT | トレーサートークンの作成 |
| トークン履歴取得 | MStracer_history | SELECT | 遅延情報の取得 |
| トークンクリーンアップ | MStracer_tokens/history | DELETE | トークン履歴の削除 |

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

#### MStracer_tokens (distribution database)

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | tracer_id | 自動生成 | トレーサートークンID |
| INSERT | publisher_commit | 現在時刻 | パブリッシャーコミット時刻 |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| N/A | ConnectionError | パブリッシャー/ディストリビューター接続失敗 | 接続情報確認 |
| N/A | LoadProperties失敗 | パブリケーション未存在 | パブリケーション名確認 |
| N/A | TimeToLive超過 | トークンが時間内にサブスクライバーに到達しない | レプリケーション状態確認 |

### リトライ仕様

TimeToLive指定時は、1秒間隔でサブスクライバー到達を確認するポーリングを実行。

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

PostTracerToken()は個別トランザクションで実行。遅延測定自体は読み取り専用操作。

## パフォーマンス要件

トレーサートークン発行は即座に完了。遅延測定はレプリケーション構成に依存（通常数秒〜数分）。

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

- パブリッシャーおよびディストリビューターへのsysadmin権限が必要
- SqlCredentialはSecureStringとして処理

## 備考

- SQL Server Management Studioのインストールが必要（RMOライブラリ依存）
- 157行目にバックティック（`）が残存している可能性
- ディストリビューターは自動検出（ReplicationServer.DistributionServer）
- Mergeレプリケーションはサポートされていない

---

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

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

### 推奨読解順序

#### Step 1: 関数構造とパラメータを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Test-DbaReplLatency.ps1 | `public/Test-DbaReplLatency.ps1` | param()ブロック（101-112行目） |

**読解のコツ**: TimeToLive、RetainToken、DisplayTokenHistoryの各パラメータがトークン処理を制御する。

#### Step 2: トレーサートークン発行処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Test-DbaReplLatency.ps1 | `public/Test-DbaReplLatency.ps1` | トークン発行（134-153行目） |

**主要処理フロー**:
1. **137行目**: TransPublicationオブジェクト作成
2. **143-144行目**: New-SqlConnectionでConnectionContext設定
3. **147行目**: LoadProperties()で存在確認
4. **152行目**: PostTracerToken()でトレーサートークン発行

#### Step 3: 遅延測定処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Test-DbaReplLatency.ps1 | `public/Test-DbaReplLatency.ps1` | ディストリビューター接続と測定（159-256行目） |

**主要処理フロー**:
- **159-164行目**: ReplicationServerからディストリビューター情報取得
- **176-184行目**: PublicationMonitorオブジェクト設定
- **192行目**: EnumTracerTokens()でトークン一覧取得
- **199-218行目**: TimeToLive待機ループとEnumTracerTokenHistory()
- **223-227行目**: TotalLatency計算

#### Step 4: 結果出力とクリーンアップを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Test-DbaReplLatency.ps1 | `public/Test-DbaReplLatency.ps1` | 結果出力（229-254行目） |

**主要処理フロー**:
- **229-246行目**: PSCustomObjectで結果オブジェクト構築
- **249-251行目**: RetainToken未指定時のCleanUpTracerTokenHistory()

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

```
Test-DbaReplLatency
    │
    ├─ [begin] Add-ReplicationLibrary
    │
    ├─ [process] Connect-DbaInstance (パブリッシャー)
    │
    ├─ Get-DbaReplPublication (Type=Transactional)
    │
    ├─ foreach (publication)
    │      │
    │      ├─ [RMO] TransPublication
    │      │      ├─ New-SqlConnection
    │      │      ├─ LoadProperties()
    │      │      └─ PostTracerToken()
    │      │
    │      └─ [RMO] ReplicationServer
    │             └─ DistributionServer/DistributionDatabase取得
    │
    ├─ Connect-DbaInstance (ディストリビューター)
    │
    └─ foreach (publication)
           │
           └─ [RMO] PublicationMonitor
                  ├─ LoadProperties()
                  ├─ EnumTracerTokens()
                  ├─ EnumTracerTokenHistory()
                  └─ CleanUpTracerTokenHistory()
```

### データフロー図

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

SqlInstance ─────────────────▶ Connect-DbaInstance ──────────────────▶ パブリッシャー接続
Database ────────────────────▶ Get-DbaReplPublication ───────────────▶ パブリケーション取得
PublicationName ─────────────────────┘
                                   │
                             TransPublication ────────────────────────▶ トレーサートークン発行
                             PostTracerToken()                         │
                                   │                                   │
                             ReplicationServer ───────────────────────▶ ディストリビューター特定
                                   │
                             Connect-DbaInstance ─────────────────────▶ ディストリビューター接続
                                   │
TimeToLive ──────────────────▶ PublicationMonitor ────────────────────▶ 遅延測定
DisplayTokenHistory ─────────▶ EnumTracerTokens/History                 │
                                   │                                   │
RetainToken ─────────────────▶ CleanUpTracerTokenHistory ─────────────▶ トークンクリーンアップ
                                   │
                                   └──────────────────────────────────▶ PSCustomObject
                                                                        (TokenID, Latency, etc.)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Test-DbaReplLatency.ps1 | `public/Test-DbaReplLatency.ps1` | ソース | メイン関数定義 |
| Get-DbaReplPublication.ps1 | `public/Get-DbaReplPublication.ps1` | ソース | パブリケーション情報取得 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
