# 機能設計書 644-Measure-DbaDbVirtualLogFile

## 概要

本ドキュメントは、SQL Serverデータベースのトランザクションログ内のVirtual Log File（VLF）数を測定するdbatools PowerShellコマンド「Measure-DbaDbVirtualLogFile」の機能設計書です。

### 本機能の処理概要

Measure-DbaDbVirtualLogFileは、データベースのトランザクションログファイル内のVLF（Virtual Log File）数をカウントし、パフォーマンスボトルネックの特定に役立つ情報を提供するコマンドです。

**業務上の目的・背景**：VLFはSQL Serverがトランザクションログを管理する際の内部単位です。VLF数が過剰（通常50-100以上）になると、トランザクションログバックアップの遅延、データベース復旧時間の延長、極端な場合はINSERT/UPDATE/DELETE操作にも影響を与えます。これは通常、トランザクションログが小さな増分で頻繁に自動拡張された場合に発生します。本機能により、定期的な健全性チェックやパフォーマンストラブルシューティングでVLF問題を早期発見できます。

**機能の利用シーン**：
- 定期的なデータベース健全性チェック
- パフォーマンス問題発生時のトラブルシューティング
- メンテナンスウィンドウ前の状態確認
- トランザクションログ設計の検証
- データベース移行前後の比較確認

**主要な処理内容**：
1. SQL Serverインスタンスへの接続
2. 対象データベースのフィルタリング（Database/ExcludeDatabase/IncludeSystemDBs）
3. Get-DbaDbVirtualLogFileでVLF情報を取得
4. Get-DbaDbFileでログファイル成長設定を取得
5. Active/Inactive VLFのカウントと結果オブジェクト生成

**関連システム・外部連携**：
- SQL Serverインスタンス（DMV/DBCC LOGINFO）

**権限による制御**：対象データベースに対するVIEW DATABASE STATE権限またはsysadminロールが必要です。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | CLI専用 | 主機能 | コマンドライン実行のみ |

## 機能種別

診断・測定（SELECT相当） / パフォーマンス分析

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQL Serverインスタンス | - |
| SqlCredential | PSCredential | No | SQL Server接続用資格情報 | 有効なPSCredential |
| Database | object[] | No | 対象データベース名 | - |
| ExcludeDatabase | object[] | No | 除外データベース名 | - |
| IncludeSystemDBs | switch | No | システムDBを含めるフラグ | - |
| EnableException | switch | No | エラー時に例外をスロー | - |

### 入力データソース

- パイプライン入力: SqlInstance
- 直接パラメータ指定

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 | 表示 |
|--------|-----|------|------|
| ComputerName | string | SQL Serverインスタンスのコンピュータ名 | デフォルト |
| InstanceName | string | SQL Serverインスタンス名 | デフォルト |
| SqlInstance | string | 完全なインスタンス名 | デフォルト |
| Database | string | データベース名 | デフォルト |
| Total | int | 合計VLF数 | デフォルト |
| TotalCount | int | 合計VLF数（Totalの複製） | 非表示 |
| Inactive | int | 非アクティブVLF数（Status=0） | 非表示 |
| Active | int | アクティブVLF数（Status=2） | 非表示 |
| LogFileName | string | ログファイル論理名（カンマ区切り） | 非表示 |
| LogFileGrowth | string | ログファイル成長増分（カンマ区切り） | 非表示 |
| LogFileGrowthType | string | ログファイル成長タイプ（Percent/kb、カンマ区切り） | 非表示 |

### 出力先

パイプライン出力（PSCustomObject、Select-DefaultViewでデフォルト5プロパティ表示）

## 処理フロー

### 処理シーケンス

```
1. SQL Serverへの接続
   └─ Connect-DbaInstanceで接続確立

2. データベースコレクションの構築
   ├─ Database指定時: 指定DBでフィルタ
   ├─ ExcludeDatabase指定時: 除外DBを除去
   └─ IncludeSystemDBs未指定時: システムDBを除去

3. 各データベースに対してループ
   ├─ Get-DbaDbVirtualLogFile でVLF情報取得
   ├─ Get-DbaDbFile でログファイル情報取得（Type=1）
   ├─ Active VLFカウント（Status=2）
   ├─ Inactive VLFカウント（Status=0）
   └─ 結果オブジェクト生成と出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B[SqlInstanceループ]
    B --> C[Connect-DbaInstance]
    C --> D{接続成功?}
    D -->|No| E[Stop-Function]
    D -->|Yes| F[データベース一覧取得]
    E --> B
    F --> G{Database指定?}
    G -->|Yes| H[指定DBでフィルタ]
    G -->|No| I[全DB使用]
    H --> J{ExcludeDatabase指定?}
    I --> J
    J -->|Yes| K[除外DBを除去]
    J -->|No| L{IncludeSystemDBs?}
    K --> L
    L -->|No| M[システムDB除去]
    L -->|Yes| N[データベースループ]
    M --> N
    N --> O[Get-DbaDbVirtualLogFile]
    O --> P[Get-DbaDbFile Type=1]
    P --> Q[Active/Inactive カウント]
    Q --> R[結果オブジェクト出力]
    R --> S{次DB?}
    S -->|Yes| N
    S -->|No| T{次インスタンス?}
    T -->|Yes| B
    T -->|No| U[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | システムDB除外 | デフォルトでシステムDB（master, model, msdb, tempdb）を除外 | IncludeSystemDBs未指定時 |
| BR-002 | VLFステータス判定 | Status=2がActive、Status=0がInactive | 常時 |
| BR-003 | 単一VLFカウント | Active/Inactiveが1件でCount=nullの場合は1とカウント | 常時 |

### 計算ロジック

- Total = $data.Count（Get-DbaDbVirtualLogFileの結果件数）
- Active = Status=2のVLF件数（1件でnullの場合は1）
- Inactive = Status=0のVLF件数（1件でnullの場合は1）

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

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

本機能はデータベースに対する変更操作を行いません。DMVおよびDBCC LOGINFOの読み取りのみを実行します。

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | ConnectionError | SQL Server接続失敗 | 接続情報を確認 |
| - | QueryError | VLF情報取得失敗 | データベース状態と権限を確認 |

### リトライ仕様

リトライなし（データベース単位でContinueしてスキップ）

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

該当なし（読み取り専用操作）

## パフォーマンス要件

- データベースあたり通常100ms以下
- VLF数が多い場合（数千以上）は取得に時間がかかる場合あり

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

- VIEW DATABASE STATE権限またはsysadminロールが必要
- 資格情報はPSCredentialオブジェクトで安全に管理

## 備考

- VLF数が50-100以上の場合はトランザクションログの再設計を検討
- Expand-SqlTLogResponsiblyでVLF数を削減可能
- 参考URL: http://www.sqlskills.com/blogs/kimberly/transaction-log-vlfs-too-many-or-too-few/

---

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

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

### 推奨読解順序

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

出力オブジェクトの構造とSelect-DefaultViewの関係を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Measure-DbaDbVirtualLogFile.ps1 | `public/Measure-DbaDbVirtualLogFile.ps1` | L139-151の出力オブジェクト定義 |

**読解のコツ**: Select-DefaultViewでデフォルト表示プロパティが5つに制限されています。全プロパティはSelect-Object *で確認できます。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Measure-DbaDbVirtualLogFile.ps1 | `public/Measure-DbaDbVirtualLogFile.ps1` | processブロック全体の流れ |

**主要処理フロー**:
1. **111行目**: processブロック開始
2. **112-117行目**: Connect-DbaInstanceで接続
3. **119-129行目**: データベースフィルタリング
4. **131-155行目**: 各データベースでのVLF情報取得と結果出力

#### Step 3: VLFカウントロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Measure-DbaDbVirtualLogFile.ps1 | `public/Measure-DbaDbVirtualLogFile.ps1` | L133-137のVLFカウント |

**主要処理フロー**:
- **133行目**: Get-DbaDbVirtualLogFileで全VLF情報取得
- **134行目**: Get-DbaDbFileでログファイル情報取得（Type=1）
- **136行目**: Status=2でActiveをフィルタ
- **137行目**: Status=0でInactiveをフィルタ
- **146-147行目**: 単一VLFの場合のnullハンドリング

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

```
Measure-DbaDbVirtualLogFile
    │
    ├─ Connect-DbaInstance
    │
    ├─ Get-DbaDbVirtualLogFile（VLF情報取得）
    │      └─ DBCC LOGINFO または sys.dm_db_log_info
    │
    └─ Get-DbaDbFile（ログファイル情報取得）
           └─ Type = 1 でフィルタ
```

### データフロー図

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

SqlInstance ──────────┐
                      │
Database ─────────────┼──▶ Connect-DbaInstance ───────┐
                      │                                │
ExcludeDatabase ──────┤                                ▼
                      │    ┌─────────────────────────────────┐
IncludeSystemDBs ─────┘    │ Get-DbaDbVirtualLogFile         │
                           │ Get-DbaDbFile                   │
                           └─────────────────────────────────┘
                                        │
                                        ▼
                                 PSCustomObject
                                 (ComputerName,
                                  Database,
                                  Total,
                                  Active,
                                  Inactive,
                                  LogFileName, etc.)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Measure-DbaDbVirtualLogFile.ps1 | `public/Measure-DbaDbVirtualLogFile.ps1` | ソース | メインコマンド実装 |
| Get-DbaDbVirtualLogFile.ps1 | `public/Get-DbaDbVirtualLogFile.ps1` | ソース | VLF詳細情報取得 |
| Get-DbaDbFile.ps1 | `public/Get-DbaDbFile.ps1` | ソース | データベースファイル情報取得 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
