# 機能設計書 106-Get-DbaDbLogSpace

## 概要

本ドキュメントは、SQL Serverデータベースのトランザクションログ使用量と容量情報を取得するGet-DbaDbLogSpace機能の設計仕様を定義する。

### 本機能の処理概要

本機能は、データベースごとの詳細なトランザクションログメトリクス（合計サイズ、使用率、使用バイト数）を収集する。SQL Server 2012以降ではsys.dm_db_log_space_usage DMVを使用し、旧バージョンではDBCC SQLPERF(logspace)を使用する。

**業務上の目的・背景**：トランザクションログの容量不足は、トランザクションの失敗やデータベースの停止につながる重大な問題である。本機能により、ログ容量の上限に近づいているデータベースを特定し、予期しないログの肥大化を防止し、ログファイルのサイジング戦略を最適化できる。

**機能の利用シーン**：
- 定期的なログスペース監視
- ログファイルサイズ計画
- トランザクションログ肥大化の早期検知
- バックアップ戦略の最適化（ログバックアップ頻度の判断）
- パフォーマンス問題のトラブルシューティング

**主要な処理内容**：
1. SQL Serverインスタンスへの接続
2. 対象データベースのフィルタリング
3. SQL Serverバージョンに基づく取得方法の選択
4. ログスペース情報の収集と出力

**関連システム・外部連携**：SQL Serverのsys.dm_db_log_space_usage DMVまたはDBCC SQLPERF(logspace)を使用。

**権限による制御**：VIEW DATABASE STATE（DMV用）またはsysadmin（DBCC SQLPERF用）の権限が必要。

## 関連画面

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 62 | 空間・メモリ情報 | 関連機能 | データベース空間使用量の取得と関連 |

## 機能種別

データ取得・監視処理（Storage monitoring）

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象のSQL Serverインスタンス | パイプライン入力対応、Mandatory |
| SqlCredential | PSCredential | No | 代替認証情報 | Windows/SQL認証、AD統合認証 |
| Database | string[] | No | 対象データベース名 | ワイルドカード対応 |
| ExcludeDatabase | string[] | No | 除外するデータベース名 | ワイルドカード対応 |
| ExcludeSystemDatabase | switch | No | システムデータベースを除外 | - |
| EnableException | switch | No | 例外処理モードの切り替え | - |

### 入力データソース

- SqlInstance: コマンドラインパラメータまたはパイプライン入力

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverをホストするコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名（サービス名） |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| Database | string | データベース名 |
| LogSize | dbasize | トランザクションログの合計サイズ（例: "10 MB", "1 GB"） |
| LogSpaceUsedPercent | decimal | 使用中のログスペースの割合（0-100） |
| LogSpaceUsed | dbasize | 使用中のログスペースのサイズ |

### 出力先

PowerShellパイプライン（PSCustomObject）

## 処理フロー

### 処理シーケンス

```
1. インスタンスごとの処理ループ
   └─ Connect-DbaInstanceで接続
2. データベースのフィルタリング
   └─ IsAccessibleなDBのみ対象
   └─ Database/ExcludeDatabase/ExcludeSystemDatabaseパラメータ適用
3. SQL Serverバージョン判定
   └─ versionMajor >= 11（SQL Server 2012以上）かどうか
4a. SQL Server 2012以降の場合
   └─ sys.dm_db_log_space_usage DMVクエリ実行
4b. SQL Server 2008以前の場合
   └─ DBCC SQLPERF(LOGSPACE)実行
5. 結果の構造化と出力
   └─ dbasize型でサイズをフォーマット
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{インスタンスループ}
    B -->|次のインスタンス| C[Connect-DbaInstance]
    C --> D{接続成功?}
    D -->|No| E[エラー出力]
    E --> B
    D -->|Yes| F[DBフィルタリング]
    F --> G{versionMajor >= 11?}
    G -->|Yes| H[DMV使用]
    G -->|No| I[DBCC SQLPERF使用]
    H --> J{DBループ}
    J -->|次のDB| K[sys.dm_db_log_space_usage]
    K --> L[PSCustomObject出力]
    L --> J
    J -->|完了| B
    I --> M[DBCC SQLPERF実行]
    M --> N{結果ループ}
    N -->|次の結果| O[PSCustomObject出力]
    O --> N
    N -->|完了| B
    B -->|完了| P[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-601 | バージョン分岐 | SQL Server 2012以上ではDMV、それ以前はDBCC SQLPERF使用 | 常時 |
| BR-602 | システムDB除外 | ExcludeSystemDatabaseスイッチでmaster/model/msdb/tempdbを除外 | スイッチ指定時 |
| BR-603 | サイズフォーマット | dbasize型で人間が読みやすい形式に変換 | 出力時 |

### 計算ロジック

**SQL Server 2012以降（DMV）**：
- LogSize: `total_log_size_in_bytes`をdbasize型に変換
- LogSpaceUsedPercent: `used_log_space_in_percent`を直接使用
- LogSpaceUsed: `used_log_space_in_bytes`をdbasize型に変換

**SQL Server 2008以前（DBCC SQLPERF）**：
- LogSize: `'Log Size (MB)' * 1MB`をdbasize型に変換
- LogSpaceUsedPercent: `'Log Space Used (%)'`を直接使用
- LogSpaceUsed: `'Log Size (MB)' * ('Log Space Used (%)' / 100) * 1MB`で計算

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

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

| 操作 | 対象テーブル/ビュー | 操作種別 | 概要 |
|-----|-------------|---------|------|
| ログ情報取得 | sys.dm_db_log_space_usage | SELECT | SQL Server 2012以降 |
| ログ情報取得 | DBCC SQLPERF(LOGSPACE) | DBCC | SQL Server 2008以前 |

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

#### sys.dm_db_log_space_usage

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | total_log_size_in_bytes | 合計ログサイズ（バイト） | - |
| SELECT | used_log_space_in_percent | 使用率（パーセント） | - |
| SELECT | used_log_space_in_bytes | 使用サイズ（バイト） | - |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| ConnectionError | 接続エラー | SQL Serverへの接続失敗 | Stop-Functionで処理継続 |
| - | Stop-Function | ログ情報の収集失敗 | エラー出力して処理継続 |

### リトライ仕様

リトライは実装されていない。エラー発生時は次のデータベースの処理を継続。

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

読み取り専用操作のため、トランザクション管理は不要。

## パフォーマンス要件

DMVまたはDBCC SQLPERFは軽量な操作で、即座に完了。

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

- VIEW DATABASE STATE権限（DMV用）またはsysadmin（DBCC SQLPERF用）が必要
- SqlCredentialパラメータで代替認証情報をサポート

## 備考

- 関連コマンド：Get-DbaDbSpace（データベース全体の空間使用量）
- Central Management Serverからの一括実行が可能（パイプライン対応）

---

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

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

### 推奨読解順序

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

出力オブジェクトの構造とdbasize型の使用を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaDbLogSpace.ps1 | `public/Get-DbaDbLogSpace.ps1` | 129-137行目：DMV使用時の出力構造 |
| 1-2 | Get-DbaDbLogSpace.ps1 | `public/Get-DbaDbLogSpace.ps1` | 147-155行目：DBCC使用時の出力構造 |

**読解のコツ**: [dbasize]型キャストにより、バイト数が人間が読みやすい形式（"10 MB"等）に自動変換される。

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

パラメータ定義とバージョン分岐を確認。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaDbLogSpace.ps1 | `public/Get-DbaDbLogSpace.ps1` | 90-99行目：パラメータ定義 |

**主要処理フロー**:
1. **102-107行目**: インスタンス接続
2. **108-118行目**: データベースフィルタリング
3. **122行目**: バージョン判定（versionMajor >= 11）
4. **123-138行目**: DMV使用処理（SQL Server 2012以降）
5. **139-157行目**: DBCC SQLPERF使用処理（旧バージョン）

#### Step 3: バージョン別処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaDbLogSpace.ps1 | `public/Get-DbaDbLogSpace.ps1` | 125行目：DMVクエリ |
| 3-2 | Get-DbaDbLogSpace.ps1 | `public/Get-DbaDbLogSpace.ps1` | 141行目：DBCC SQLPERFクエリ |

**主要処理フロー**:
- **122行目**: `$server.versionMajor -ge 11`でバージョン判定
- **125行目**: `sys.dm_db_log_space_usage`から直接取得
- **141行目**: `DBCC SQLPERF(LOGSPACE)`で全DB一括取得
- **154行目**: DBCC結果からLogSpaceUsedを計算

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

```
Get-DbaDbLogSpace
    │
    ├─ Connect-DbaInstance
    │
    ├─ Stop-Function（エラー処理）
    │
    └─ $server.Query()
           ├─ sys.dm_db_log_space_usage（2012以降）
           └─ DBCC SQLPERF(LOGSPACE)（旧バージョン）
```

### データフロー図

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

SqlInstance ───▶ Connect-DbaInstance
                      │
                      ▼
               ┌─────────────────┐
Database ────▶ │ DBフィルタリング │
               └────────┬────────┘
                        │
                        ▼
               ┌─────────────────┐
               │ バージョン判定  │
               │ (>= 2012?)     │
               └────────┬────────┘
                        │
            ┌───────────┴───────────┐
            ▼                       ▼
    ┌───────────────┐      ┌───────────────┐
    │ DMV使用       │      │ DBCC SQLPERF  │
    │ (foreach DB)  │      │ (一括取得)    │
    └───────┬───────┘      └───────┬───────┘
            │                       │
            └───────────┬───────────┘
                        ▼
               ┌─────────────────┐      ┌─ ComputerName
               │ PSCustomObject  │──────┼─ Database
               └─────────────────┘      ├─ LogSize (dbasize)
                                        ├─ LogSpaceUsedPercent
                                        └─ LogSpaceUsed (dbasize)
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaDbLogSpace.ps1 | `public/Get-DbaDbLogSpace.ps1` | ソース | メイン処理 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
