# 画面設計書 161-バックアップスループット

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるバックアップスループット測定機能（Measure-DbaBackupThroughput）の画面設計書です。msdbデータベースのバックアップ履歴から、バックアップパフォーマンスに関する詳細なスループット統計を計算・分析する機能を提供します。

### 本画面の処理概要

**業務上の目的・背景**：データベース管理者（DBA）にとって、バックアップ処理のパフォーマンス分析は極めて重要な業務です。バックアップウィンドウの管理、ストレージボトルネックの特定、RTO要件への適合確認など、多くの運用上の意思決定に直結します。本機能は、バックアップ履歴から自動的にスループット統計を算出し、パフォーマンス傾向の把握や問題箇所の特定を効率化します。

**画面へのアクセス方法**：PowerShellコマンドラインから `Measure-DbaBackupThroughput` コマンドレットを実行してアクセスします。パイプライン入力にも対応しており、複数インスタンスを一括で分析可能です。

**主要な操作・処理内容**：
1. SQL Serverインスタンスに接続し、msdbデータベースのバックアップ履歴を取得
2. 指定されたバックアップタイプ（Full/Log/Differential等）でフィルタリング
3. バックアップサイズと所要時間からスループット（MB/秒）を計算
4. データベースごとに平均・最小・最大スループット、平均サイズ、平均所要時間を集計
5. 分析結果をPSCustomObjectとして出力

**画面遷移**：本機能は単独のコマンドレットとして動作し、他の画面への遷移は発生しません。ただし、出力結果は他のコマンドレットにパイプで渡すことが可能です。

**権限による表示制御**：バックアップ履歴の参照にはmsdbデータベースへの読み取り権限が必要です。sysadmin権限またはdb_datareaaderロールを持つユーザーが実行可能です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 41 | Measure-DbaBackupThroughput | 主機能 | バックアップスループットの測定 |
| 37 | Get-DbaDbBackupHistory | 内部呼出 | バックアップ履歴データの取得 |
| 327 | Connect-DbaInstance | 内部呼出 | SQL Serverインスタンスへの接続 |

## 画面種別

CLI（コマンドラインインターフェース）- 分析・集計

## URL/ルーティング

PowerShellコマンド: `Measure-DbaBackupThroughput`

## 入出力項目

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstanceParameter[] | Yes | 接続先SQL Serverインスタンス |
| SqlCredential | PSCredential | No | SQL Server認証用の資格情報 |
| Database | object[] | No | 分析対象データベース（ワイルドカード対応） |
| ExcludeDatabase | object[] | No | 除外するデータベース（ワイルドカード対応） |
| Type | string | No | バックアップタイプ（Full/Log/Differential等）、デフォルトはFull |
| Since | datetime | No | 指定日時以降のバックアップのみを分析 |
| Last | switch | No | 各データベースの最新バックアップのみを分析 |
| DeviceType | string[] | No | バックアップデバイスタイプでフィルタリング |
| EnableException | switch | No | 例外を有効化してtry/catchで捕捉可能にする |

### 出力項目

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverインスタンスのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| Database | string | 分析対象データベース名 |
| AvgThroughput | DbaSize | 平均スループット（MB/秒） |
| AvgSize | DbaSize | 平均バックアップサイズ |
| AvgDuration | DbaTimeSpan | 平均所要時間 |
| MinThroughput | DbaSize | 最小スループット |
| MaxThroughput | DbaSize | 最大スループット |
| MinBackupDate | DbaDateTime | 分析対象期間の最古バックアップ日時 |
| MaxBackupDate | DbaDateTime | 分析対象期間の最新バックアップ日時 |
| BackupCount | int | 分析対象バックアップ件数 |

## 表示項目

出力オブジェクトのすべてのプロパティがPowerShellコンソールに表示されます。DbaSize型のプロパティは自動的に適切な単位（Bytes/KB/MB/GB/TB）でフォーマットされます。

## イベント仕様

### 1-コマンド実行

1. **SqlInstance接続処理**（行146-149）: Connect-DbaInstanceを使用してSQL Serverに接続
2. **データベースコレクション取得**（行151-159）: 対象データベースリストを取得し、除外データベースを適用
3. **バックアップ履歴取得**（行162-170）: Get-DbaDbBackupHistoryを呼び出してバックアップ履歴を取得
4. **スループット計算**（行172-184）: 各バックアップのサイズと所要時間からスループットを計算
5. **統計集計**（行187-209）: データベースごとに各種統計を集計し、PSCustomObjectとして出力

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| バックアップ履歴取得 | msdb.dbo.backupset | SELECT | バックアップ履歴の参照 |
| バックアップ履歴取得 | msdb.dbo.backupmediafamily | SELECT | バックアップメディア情報の参照 |

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

#### msdb.dbo.backupset（参照のみ）

| 操作 | 項目（カラム名） | 取得条件 | 備考 |
|-----|-----------------|----------|------|
| SELECT | backup_start_date, backup_finish_date, backup_size | Get-DbaDbBackupHistory内部で使用 | スループット計算に使用 |

## メッセージ仕様

| メッセージタイプ | 条件 | メッセージ内容 |
|-----------------|------|---------------|
| VeryVerbose | 履歴取得開始時 | "Retrieving history for {database name}." |
| VeryVerbose | 平均計算開始時 | "Calculating averages for {database name}." |
| Error | 接続失敗時 | "Failure" - ConnectionError |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| SQL Server接続失敗 | Stop-Functionでエラーを記録し、次のインスタンスの処理を継続 |
| バックアップ履歴なし | 空の結果を返す（エラーにはならない） |
| 所要時間0ミリ秒 | バックアップサイズをそのままスループットとして使用（行175-176） |

## 備考

- スループットの単位変換はDbaSize型により自動的に行われ、表示時に最適な単位が選択されます
- バックアップ履歴が大量にある場合、-Sinceパラメータで分析対象期間を限定することでパフォーマンスを改善できます
- -Lastパラメータは各バックアップタイプの最新バックアップのみを分析するため、迅速なスポットチェックに適しています

---

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

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

### 推奨読解順序

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

スループット計算の出力形式と、内部で使用されるバックアップ履歴データの構造を理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Measure-DbaBackupThroughput.ps1 | `public/Measure-DbaBackupThroughput.ps1` | 行195-208の出力オブジェクト構造（PSCustomObject） |

**読解のコツ**: DbaSize、DbaTimeSpan、DbaDateTimeは dbatools独自の型で、表示時に自動フォーマットされます。

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

処理の起点となるパラメータバインディングと接続処理を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Measure-DbaBackupThroughput.ps1 | `public/Measure-DbaBackupThroughput.ps1` | 行129-141のパラメータ定義とバリデーション |

**主要処理フロー**:
1. **行143**: process ブロック開始、各インスタンスのループ処理
2. **行144-149**: Connect-DbaInstanceでSQL Server接続
3. **行151-159**: 対象データベースの決定と除外処理

#### Step 3: バックアップ履歴取得処理を理解する

Get-DbaDbBackupHistoryの呼び出しとフィルタリング処理を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Measure-DbaBackupThroughput.ps1 | `public/Measure-DbaBackupThroughput.ps1` | 行166-170のGet-DbaDbBackupHistory呼び出し |

**主要処理フロー**:
- **行166-167**: -Sinceパラメータ指定時の履歴取得
- **行168-170**: -Lastパラメータ指定時の最新履歴取得

#### Step 4: スループット計算と集計処理を理解する

メイン処理であるスループット計算アルゴリズムを理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Measure-DbaBackupThroughput.ps1 | `public/Measure-DbaBackupThroughput.ps1` | 行172-209のスループット計算と統計集計 |

**主要処理フロー**:
- **行173**: New-TimeSpanでバックアップ所要時間を計算
- **行175-179**: 所要時間が0の場合の処理とスループット計算（MB/秒）
- **行181**: Add-MemberでMBpsプロパティを動的追加
- **行189-193**: Measure-Objectで各種統計値を算出
- **行195-208**: 最終出力オブジェクトの生成

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

```
Measure-DbaBackupThroughput
    |
    +-- Connect-DbaInstance (行146)
    |       └── SQL Serverへの接続確立
    |
    +-- server.Databases (行152-154)
    |       └── データベースコレクション取得
    |
    +-- Get-DbaDbBackupHistory (行167, 169)
    |       └── バックアップ履歴データ取得
    |
    +-- スループット計算ロジック (行172-184)
    |       +-- New-TimeSpan (行173)
    |       └── Add-Member (行181)
    |
    └-- 統計集計・出力 (行187-209)
            +-- Measure-Object (行189-193)
            └-- [PSCustomObject] 出力 (行195-208)
```

### データフロー図

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

SqlInstance ──────────────┐
                          │
SqlCredential ────────────┼──> Connect-DbaInstance ──> SMO Server オブジェクト
                          │
Database/ExcludeDatabase ─┼──> データベースフィルタリング ──> データベースリスト
                          │
Type/Since/Last ──────────┼──> Get-DbaDbBackupHistory ──> バックアップ履歴
                          │
                          └──> スループット計算 ──────────┐
                                      │                   │
                                      v                   v
                              [各バックアップのMBps]  [統計集計]
                                                          │
                                                          v
                                                    PSCustomObject
                                                    (スループット統計)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Measure-DbaBackupThroughput.ps1 | `public/Measure-DbaBackupThroughput.ps1` | ソース | 主機能の実装 |
| Get-DbaDbBackupHistory.ps1 | `public/Get-DbaDbBackupHistory.ps1` | ソース | バックアップ履歴取得（内部呼出） |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続処理 |
| dbatools.Types.ps1xml | `xml/dbatools.Types.ps1xml` | 設定 | DbaSize等カスタム型の定義 |
