# 画面設計書 254-ログスペース

## 概要

本ドキュメントは、dbatools PowerShellモジュールの `Get-DbaDbLogSpace` コマンドに関する画面設計書です。このコマンドは、SQL Serverデータベースのトランザクションログスペース使用状況と容量情報を取得します。

### 本画面の処理概要

**業務上の目的・背景**：トランザクションログの容量管理は、データベース運用において重要な監視項目です。ログファイルが満杯になると、トランザクションが失敗しシステム停止につながる可能性があります。このコマンドは、トランザクションログの総サイズ、使用率、使用済み容量をプロアクティブに監視し、予期しないログ増加の防止、容量上限に近づいているデータベースの特定、ログファイルサイジング計画の最適化に役立ちます。

**画面へのアクセス方法**：PowerShellコンソールまたはスクリプトから `Get-DbaDbLogSpace` コマンドを実行します。SQL Serverインスタンスをパイプラインで渡すことも可能です。

**主要な操作・処理内容**：
1. 指定されたSQL Serverインスタンスへの接続を確立
2. アクセス可能なデータベースをフィルタリング
3. SQL Server 2012以上の場合、`sys.dm_db_log_space_usage` DMVを使用
4. SQL Server 2012未満の場合、`DBCC SQLPERF(logspace)` を使用
5. 結果をPSCustomObjectとして出力（dbasize型でサイズをフォーマット）

**画面遷移**：CLIコマンドのため画面遷移はありません。出力結果は他のコマンド（`Invoke-DbaDbShrink` など）にパイプラインで渡すことができます。

**権限による表示制御**：VIEW DATABASE STATE権限が必要です。DBCC SQLPERFを使用するバージョンではALTER権限が必要な場合があります。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 106 | Get-DbaDbLogSpace | 主機能 | ログスペース使用状況の取得 |
| 170 | Invoke-DbaDbShrink | 遷移先機能 | ログファイルの縮小 |
| 637 | Get-DbaDbVirtualLogFile | 関連機能 | VLF情報の取得 |

## 画面種別

情報取得・監視（CLIコマンド）

## URL/ルーティング

該当なし（PowerShell CLIコマンド）

## 入出力項目

### 入力パラメーター

| パラメーター名 | 型 | 必須 | 説明 |
|---------------|---|-----|------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQL Serverインスタンス名（パイプライン入力対応） |
| SqlCredential | PSCredential | No | 代替認証情報 |
| Database | string[] | No | 対象データベース名（ワイルドカード対応） |
| ExcludeDatabase | string[] | No | 除外するデータベース名（ワイルドカード対応） |
| ExcludeSystemDatabase | switch | No | システムデータベースを除外 |
| EnableException | switch | No | 例外を直接スローするかどうか |

### 出力項目

| プロパティ名 | 型 | 説明 |
|-------------|---|------|
| ComputerName | string | SQL Serverインスタンスのコンピューター名 |
| InstanceName | string | SQL Serverインスタンス名（サービス名） |
| SqlInstance | string | 完全修飾インスタンス名 |
| Database | string | データベース名 |
| LogSize | dbasize | トランザクションログの総サイズ（フォーマット済み、例: "10 MB"） |
| LogSpaceUsedPercent | decimal | トランザクションログの使用率（0-100） |
| LogSpaceUsed | dbasize | 使用済みログスペース（フォーマット済み） |

## 表示項目

CLIコマンドのため、表示項目は出力オブジェクトのプロパティに依存します。

## イベント仕様

### 1-コマンド実行

コマンド実行時に以下の処理が行われます：

1. `Connect-DbaInstance` でSQL Serverに接続
2. IsAccessibleなデータベースを取得
3. Database/ExcludeDatabase/ExcludeSystemDatabaseでフィルタリング
4. バージョンに応じたログスペース取得方法を選択
   - SQL Server 2012+: `sys.dm_db_log_space_usage` DMV
   - SQL Server 2008以前: `DBCC SQLPERF(logspace)`
5. PSCustomObjectを出力（dbasize型でサイズをフォーマット）

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| コマンド実行（2012+） | sys.dm_db_log_space_usage | SELECT | ログスペース情報の読み取り |
| コマンド実行（2008以前） | DBCC SQLPERF | 実行 | ログスペース情報の取得 |

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

このコマンドは読み取り専用であり、データベースの更新は行いません。

## メッセージ仕様

| メッセージ種別 | 条件 | メッセージ内容 |
|--------------|------|---------------|
| エラー | 接続失敗時 | "Failure" + ConnectionError詳細 |
| エラー | ログスペース取得失敗 | "Unable to collect log space data on $instance." |

## 例外処理

| 例外状況 | 処理内容 |
|---------|---------|
| 接続エラー | Stop-Functionで処理を中断して次のインスタンスへ続行 |
| ログスペース取得エラー | Stop-Functionでメッセージ表示して続行 |

## 備考

- SQL Server 2012以上では `sys.dm_db_log_space_usage` DMVを使用し、より詳細な情報を取得
- SQL Server 2008以前では `DBCC SQLPERF(logspace)` を使用
- dbasize型により、出力サイズは自動的に適切な単位（MB, GB等）でフォーマット
- Central Management Server (CMS) からのパイプライン入力に対応

---

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

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

### 推奨読解順序

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaDbLogSpace.ps1 | `public/Get-DbaDbLogSpace.ps1` | 出力PSCustomObject構造（行129-137、147-155） |
| 1-2 | Get-DbaDbLogSpace.ps1 | `public/Get-DbaDbLogSpace.ps1` | dbasize型の使用方法 |

**読解のコツ**: dbasize型は、バイト数を人間が読みやすい形式（KB, MB, GB等）に自動変換するdbatools独自の型です。

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaDbLogSpace.ps1 | `public/Get-DbaDbLogSpace.ps1` | 関数定義全体（行1-160） |

**主要処理フロー**:
1. **行102-107**: processブロックでSQL Serverに接続
2. **行108-118**: データベースフィルタリング（Database, ExcludeDatabase, ExcludeSystemDatabase）
3. **行122**: バージョンチェック（versionMajor -ge 11）
4. **行123-138**: SQL Server 2012+の処理（sys.dm_db_log_space_usage）
5. **行139-157**: SQL Server 2008以前の処理（DBCC SQLPERF）

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

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

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

```
Get-DbaDbLogSpace
    │
    ├─ Connect-DbaInstance
    │
    ├─ $server.Databases (フィルタリング)
    │      ├─ Where-Object IsAccessible
    │      ├─ Where-Object Name -in $Database
    │      ├─ Where-Object Name -NotIn $ExcludeDatabase
    │      └─ Where-Object IsSystemObject -eq $false
    │
    └─ バージョン分岐
           ├─ (2012+) $server.query('SELECT * FROM sys.dm_db_log_space_usage')
           └─ (2008以前) $server.Query("DBCC SQLPERF(LOGSPACE)")
```

### データフロー図

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

SqlInstance ───▶ Connect-DbaInstance ───▶ SMO Server
                           │
Database/Exclude ──▶ データベースフィルタ
                           │
                           ▼
                    バージョン分岐
                    ├─(2012+)──▶ sys.dm_db_log_space_usage
                    └─(2008)───▶ DBCC SQLPERF(LOGSPACE)
                           │
                           ▼
                      dbasize変換 ───▶ PSCustomObject
                           │
                           ▼
                      パイプライン出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaDbLogSpace.ps1 | `public/Get-DbaDbLogSpace.ps1` | ソース | メイン関数定義 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
| Stop-Function.ps1 | `internal/functions/flowcontrol/Stop-Function.ps1` | ソース | エラーハンドリング |
