# 画面設計書 152-メモリ使用量

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるメモリ使用量監視機能の設計を定義する。SQL Server関連サービス（Database Engine、SSAS、SSIS）のメモリ使用状況とメモリプレッシャー状態を監視・分析するための機能群を提供する。

### 本画面の処理概要

本機能は、SQL Serverおよび関連サービスのメモリ使用状況を包括的に監視し、メモリに関する問題の診断と分析を支援する。

**業務上の目的・背景**：SQL Serverのパフォーマンス問題の多くはメモリ関連の設定や使用状況に起因する。本機能は、Memory Manager、Plan Cache、Buffer Managerなどの主要コンポーネントごとのメモリ使用状況を詳細に把握することで、メモリプレッシャーの原因特定やキャパシティプランニングを支援する。また、リソースモニターリングバッファからメモリ通知イベントを取得し、過去のメモリプレッシャー発生状況を分析できる。

**画面へのアクセス方法**：PowerShellコンソールまたはスクリプトから以下のコマンドを実行してアクセスする：
- `Get-DbaMemoryUsage -ComputerName <コンピュータ名>` - Windowsパフォーマンスカウンターからメモリ使用量取得
- `Get-DbaMemoryCondition -SqlInstance <インスタンス名>` - メモリプレッシャー通知履歴取得

**主要な操作・処理内容**：
1. Memory Manager カウンター（Server Memory、Connection Memory、Lock Memory等）の取得
2. Plan Cache カウンター（Procedure plans、Ad-hoc plans等）の取得
3. Buffer Manager カウンター（Free pages、Stolen pages、Total pages等）の取得
4. SSAS、SSISサービスのメモリカウンター取得
5. リソースモニターリングバッファからのメモリプレッシャー通知履歴取得
6. 物理メモリ、ページファイル、仮想アドレス空間の使用状況分析

**画面遷移**：
- 本機能はスタンドアロンで動作し、他の機能への直接的な画面遷移はない
- パイプラインで他のdbatools機能（ConvertTo-DbaDataTable等）と連携可能

**権限による表示制御**：
- パフォーマンスカウンター取得には対象コンピュータのローカル管理者権限が必要
- sys.dm_os_ring_buffers への VIEW SERVER STATE 権限が必要

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 410 | Get-DbaMemoryUsage | 主機能 | Windowsパフォーマンスカウンターからメモリ使用量を収集 |
| 409 | Get-DbaMemoryCondition | 補助機能 | リソースモニターリングバッファからメモリプレッシャー通知を取得 |

## 画面種別

一覧 / 診断情報表示

## URL/ルーティング

PowerShellコマンドレット:
- `Get-DbaMemoryUsage`
- `Get-DbaMemoryCondition`

## 入出力項目

### Get-DbaMemoryUsage パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|------|------|------|
| ComputerName | DbaInstanceParameter[] | No | 対象コンピュータ（デフォルト: ローカル） |
| Credential | PSCredential | No | 認証用資格情報 |
| MemoryCounterRegex | string | No | Memory Managerカウンターフィルタ正規表現 |
| PlanCounterRegex | string | No | Plan Cacheカウンターフィルタ正規表現 |
| BufferCounterRegex | string | No | Buffer Managerカウンターフィルタ正規表現 |
| SSASCounterRegex | string | No | SSASカウンターフィルタ正規表現 |
| SSISCounterRegex | string | No | SSISカウンターフィルタ正規表現 |
| EnableException | switch | No | 例外処理の有効化 |

### Get-DbaMemoryCondition パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|------|------|------|
| SqlInstance | DbaInstance[] | Yes | 接続先SQL Serverインスタンス |
| SqlCredential | PSCredential | No | SQL Server認証用資格情報 |
| EnableException | switch | No | 例外処理の有効化 |

## 表示項目

### Get-DbaMemoryUsage 出力プロパティ

| プロパティ名 | 型 | 説明 |
|-------------|------|------|
| ComputerName | string | カウンター収集元のコンピュータ名 |
| SqlInstance | string | SQL Serverインスタンス名 |
| CounterInstance | string | パフォーマンスカウンターインスタンス識別子 |
| Counter | string | パフォーマンスカウンター名 |
| Pages | long | ページ数（Buffer/Plan Cacheのみ、他はnull） |
| Memory | dbasize | メモリ使用量（Bytes、KB、MB、GB単位で表示可能） |

### Get-DbaMemoryCondition 出力プロパティ

| プロパティ名 | 型 | 説明 |
|-------------|------|------|
| ComputerName | string | SQL Serverインスタンスのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| Runtime | datetime | クエリ実行日時 |
| NotificationTime | datetime | メモリプレッシャーイベント発生日時 |
| NotificationType | string | 通知タイプ（Low Physical Memory等） |
| MemoryUtilizationPercent | int | メモリ使用率（0-100） |
| TotalPhysicalMemory | dbasize | 物理メモリ総量 |
| AvailablePhysicalMemory | dbasize | 使用可能物理メモリ |
| TotalPageFile | dbasize | ページファイル総量 |
| AvailablePageFile | dbasize | 使用可能ページファイル |
| TotalVirtualAddressSpace | dbasize | 仮想アドレス空間総量 |
| AvailableVirtualAddressSpace | dbasize | 使用可能仮想アドレス空間 |
| NodeId | int | NUMAノードID |
| SQLReservedMemory | dbasize | SQL Server予約メモリ |
| SQLCommittedMemory | dbasize | SQL Serverコミット済みメモリ |
| RecordId | int | リングバッファレコードID |
| Type | string | レコードタイプ |
| Indicators | int | メモリプレッシャーインジケータ |
| RecordTime | long | レコードタイムスタンプ（ミリ秒） |
| CurrentTime | long | 現在時刻（sys.ms_ticks） |

## イベント仕様

### 1-Get-DbaMemoryUsage実行

1. Resolve-DbaNetworkNameで対象コンピュータ名を解決
2. Invoke-Command2でリモートスクリプトブロックを実行
3. Get-Counterで以下のカウンターセットを照会：
   - *sql*:Memory Manager* - Memory Managerカウンター
   - *sql*:Plan Cache* - Plan Cacheカウンター
   - *Buffer Manager* - Buffer Managerカウンター
   - MSAS*:Memory - SSASメモリカウンター
   - *SSIS* - SSISメモリカウンター
4. 正規表現パターンでフィルタリング
5. dbasizeオブジェクトに変換して出力

### 2-Get-DbaMemoryCondition実行

1. Connect-DbaInstanceでSQL Serverインスタンスに接続（最小バージョン: SQL Server 2005）
2. sys.dm_os_ring_buffersからRING_BUFFER_RESOURCE_MONITORレコードを照会
3. XMLデータをパースしてメモリ情報を抽出
4. sys.dm_os_sys_infoからタイムスタンプ情報を取得
5. 通知時刻を計算
6. dbasizeオブジェクトに変換して出力

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| Get-DbaMemoryUsage | なし | - | Windowsパフォーマンスカウンターのみ |
| Get-DbaMemoryCondition | sys.dm_os_ring_buffers | SELECT | リソースモニターリングバッファ取得 |
| Get-DbaMemoryCondition | sys.dm_os_sys_info | SELECT | システム情報取得 |

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

本機能は読み取り専用のため、データベースへの更新は発生しない。

## メッセージ仕様

| メッセージID | レベル | 条件 | メッセージ内容 |
|-------------|--------|------|---------------|
| - | Warning | コンピュータ名解決失敗 | "Can't resolve {computer}." |
| - | Verbose | Memory Managerカウンター検索 | "Searching for Memory Manager Counters on {Computer}" |
| - | Verbose | カウンター未検出 | "No Memory Manager Counters on {Computer}" |
| - | Error | 接続失敗 | "Failure" |
| - | Error | データ収集失敗 | "Issue collecting data" |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| SQL Server接続失敗 | ConnectionError カテゴリでStop-Function実行、処理継続 |
| コンピュータ名解決失敗 | 警告メッセージ出力、該当コンピュータをスキップ |
| パフォーマンスカウンター取得失敗 | SilentlyContinue、次のカウンターセットへ |
| SQL Server 2005未満 | MinimumVersion 9 により自動的にスキップ |

## 備考

- Get-DbaMemoryUsageはローカル管理者権限が必要
- SSRSにはメモリカウンターがなく、memory shrinksとmemory pressure stateのみ
- Memory ManagerとSSASカウンターはKB単位、SSISはMB単位で返される
- Plan CacheとBuffer Managerは8KBページ単位で返される
- dbasizeオブジェクトは.Kilobytes, .Megabytes, .Gigabytes, .Terabytesプロパティでアクセス可能
- 参考資料:
  - https://msdn.microsoft.com/en-us/library/ms137622.aspx (SSISカウンター)

---

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

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

### 推奨読解順序

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

メモリ使用量情報のデータ構造を理解する。出力はdbasizeオブジェクトを含むPSCustomObject。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaMemoryUsage.ps1 | `public/Get-DbaMemoryUsage.ps1` | 235-242行目: 出力PSCustomObjectの構造定義、dbasizeへの変換 |
| 1-2 | Get-DbaMemoryCondition.ps1 | `public/Get-DbaMemoryCondition.ps1` | 156-178行目: 出力PSCustomObjectの構造定義 |

**読解のコツ**: [dbasize]型キャストに注目。バイト単位への統一変換を行う。

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

処理の起点となるコマンドレット関数を特定。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaMemoryUsage.ps1 | `public/Get-DbaMemoryUsage.ps1` | 104-116行目: param()ブロックでパラメータ定義を確認 |
| 2-2 | Get-DbaMemoryCondition.ps1 | `public/Get-DbaMemoryCondition.ps1` | 79-85行目: param()ブロックでパラメータ定義を確認 |

**主要処理フロー (Get-DbaMemoryUsage)**:
1. **229-232行目**: Resolve-DbaNetworkNameでコンピュータ名解決
2. **234行目**: Invoke-Command2でリモートスクリプトブロック実行
3. **118-226行目**: スクリプトブロック内でGet-Counter実行
4. **235-242行目**: 結果をdbasizeに変換して出力

#### Step 3: スクリプトブロック処理を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaMemoryUsage.ps1 | `public/Get-DbaMemoryUsage.ps1` | 118-226行目: リモート実行されるスクリプトブロック全体 |

**主要処理フロー**:
- **128-145行目**: Memory Managerカウンター収集
- **148-165行目**: Plan Cacheカウンター収集
- **168-185行目**: Buffer Managerカウンター収集
- **188-205行目**: SSASカウンター収集
- **208-225行目**: SSISカウンター収集

#### Step 4: リングバッファクエリを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Get-DbaMemoryCondition.ps1 | `public/Get-DbaMemoryCondition.ps1` | 88-140行目: XMLパースを含むリングバッファクエリ |

**主要処理フロー**:
- **111-131行目**: サブクエリでXMLをパース
- **91-92行目**: NotificationTime計算（ms_ticksとRecordTimeから算出）
- **164-172行目**: dbasizeオブジェクトへの変換（KB * 1024）

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

```
Get-DbaMemoryUsage
    |
    +-- Resolve-DbaNetworkName
    |       +-- DNS名前解決
    |
    +-- Invoke-Command2
            +-- ScriptBlock (リモート実行)
                    |
                    +-- Get-Counter (-ListSet '*sql*:Memory Manager*')
                    +-- Get-Counter (-ListSet '*sql*:Plan Cache*')
                    +-- Get-Counter (-ListSet '*Buffer Manager*')
                    +-- Get-Counter (-ListSet 'MSAS*:Memory')
                    +-- Get-Counter (-ListSet '*SSIS*')

Get-DbaMemoryCondition
    |
    +-- Connect-DbaInstance (MinimumVersion 9)
    |       +-- SMO Server Object生成
    |
    +-- Server.Query()
            +-- sys.dm_os_ring_buffers (RING_BUFFER_RESOURCE_MONITOR)
            +-- sys.dm_os_sys_info
```

### データフロー図

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

ComputerName   ------>  Resolve-DbaNetworkName  ----+
                                                    |
Credential     ------>                              |
                                                    v
*CounterRegex  ------>  Invoke-Command2        --> Get-Counter
                             |                          |
                             v                          v
                        ScriptBlock (Remote)      Counter Samples
                             |                          |
                             +---> Regex Filter <-------+
                                        |
                                        v
                                   Memory Data -----> [dbasize]
                                        |
                                        v
                                   PSCustomObject

SqlInstance    ------>  Connect-DbaInstance    ----+
                                                   |
SqlCredential  ------>                             |
                                                   v
                        Server.Query()         --> Ring Buffer XML
                             |                          |
                             v                          v
                        XML Parsing            --> Memory Metrics
                             |                          |
                             v                          v
                        [dbasize] conversion   --> PSCustomObject
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaMemoryUsage.ps1 | `public/Get-DbaMemoryUsage.ps1` | ソース | パフォーマンスカウンターからメモリ使用量取得 |
| Get-DbaMemoryCondition.ps1 | `public/Get-DbaMemoryCondition.ps1` | ソース | リングバッファからメモリ条件取得 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続処理 |
| Resolve-DbaNetworkName.ps1 | `public/Resolve-DbaNetworkName.ps1` | ソース | ネットワーク名解決 |
| Invoke-Command2.ps1 | `internal/functions/Invoke-Command2.ps1` | ソース | リモートコマンド実行 |
