# 機能設計書 139-Get-DbaProcess

## 概要

本ドキュメントは、dbatools PowerShellモジュールの`Get-DbaProcess`コマンドレットに関する機能設計書です。このコマンドレットは、SQL Serverのアクティブなプロセスとセッションの詳細な接続情報およびアクティビティ情報を取得する機能を提供します。

### 本機能の処理概要

**業務上の目的・背景**：SQL Serverの現在のデータベースアクティビティを把握することは、パフォーマンス監視、ブロッキング問題の特定、接続リークの発見、セキュリティ監査に不可欠です。本機能は、SMOのEnumProcesses()メソッドと動的管理ビュー（DMV）を組み合わせて、包括的なプロセス情報を提供します。セッション詳細、接続プロパティ、タイミングデータ、最後に実行されたSQLステートメントなどを取得できます。

**機能の利用シーン**：
- アクティブ接続の監視時
- ブロッキングプロセスの特定時
- アプリケーション接続の追跡時
- パフォーマンス問題のトラブルシューティング時
- データベースアクセスパターンの監査時

**主要な処理内容**：
1. SQL Serverインスタンスに接続
2. Server.EnumProcesses()でプロセス一覧取得
3. DMV（dm_exec_sessions, dm_exec_connections等）から追加情報取得
4. フィルタリング条件適用（Login, Hostname, Program, Database, Spid）
5. プロセス情報とDMV情報を結合して出力

**関連システム・外部連携**：
- SQL Server SMO（EnumProcesses）
- SQL Server DMV（dm_exec_sessions, dm_exec_connections, dm_exec_sql_text, endpoints）
- Connect-DbaInstance（SQL Server接続）

**権限による制御**：VIEW SERVER STATE権限が必要です。他のユーザーのセッション情報を見るにはこの権限が必要です。

## 関連画面

本機能はコマンドラインツールであり、画面機能マッピングに該当する関連画面はありません。

| 画面No | 画面名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| - | - | - | PowerShellコマンドラインで実行 |

## 機能種別

データ取得 / プロセス監視

## 入力仕様

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 | バリデーション |
|-------------|-----|-----|------|---------------|
| SqlInstance | DbaInstanceParameter[] | Yes | 対象SQL Serverインスタンス | パイプライン入力可、Mandatory |
| SqlCredential | PSCredential | No | SQL Server接続用の資格情報 | - |
| Spid | int[] | No | 特定のSPIDでフィルタ（ブロック関係含む） | - |
| Login | string[] | No | ログイン名でフィルタ | - |
| Hostname | string[] | No | クライアントホスト名でフィルタ | - |
| Program | string[] | No | アプリケーション名でフィルタ | - |
| Database | string[] | No | データベース名でフィルタ | - |
| ExcludeSpid | int[] | No | 除外するSPID | - |
| ExcludeSystemSpids | switch | No | システムSPID（1-50）を除外 | - |
| Intersect | switch | No | フィルタ条件をANDで結合（デフォルトはOR） | - |
| EnableException | switch | No | 例外処理を有効化 | - |

### 入力データソース

- SQL Server SMO: EnumProcesses()
- SQL Server DMV: dm_exec_sessions, dm_exec_connections, dm_exec_sql_text, dm_exec_requests, endpoints

## 出力仕様

### 出力データ

| 項目名 | 型 | 説明 | デフォルト表示 |
|--------|-----|------|--------------|
| ComputerName | string | SQL Serverのコンピュータ名 | Yes |
| InstanceName | string | SQL Serverインスタンス名 | Yes |
| SqlInstance | string | 完全なインスタンス名 | Yes |
| Spid | int | セッションID | Yes |
| Login | string | ログイン名 | Yes |
| LoginTime | datetime | ログイン日時 | Yes |
| Host | string | クライアントホスト名 | Yes |
| Database | string | 接続先データベース | Yes |
| BlockingSpid | int | ブロックしているSPID | Yes |
| Program | string | クライアントアプリケーション名 | Yes |
| Status | string | セッションステータス（sleeping, running等） | Yes |
| Command | string | 実行中のT-SQLコマンド | Yes |
| Cpu | int | CPU使用時間（ミリ秒） | Yes |
| MemUsage | int | メモリ使用量（8KBページ単位） | Yes |
| LastRequestStartTime | datetime | 最後のリクエスト開始時刻 | Yes |
| LastRequestEndTime | datetime | 最後のリクエスト終了時刻 | Yes |
| MinutesAsleep | int | 最後のリクエスト終了からの経過分数 | Yes |
| ClientNetAddress | string | クライアントIPアドレス | Yes |
| NetTransport | string | ネットワーク転送プロトコル | Yes |
| EncryptOption | string | 暗号化設定 | Yes |
| AuthScheme | string | 認証スキーム（NTLM, Kerberos等） | Yes |
| NetPacketSize | int | ネットワークパケットサイズ | Yes |
| ClientVersion | int | クライアントライブラリバージョン | Yes |
| HostProcessId | int | クライアントOSプロセスID | Yes |
| IsSystem | bool | システムセッションか | Yes |
| EndpointName | string | 接続エンドポイント名 | Yes |
| IsDac | bool | DAC（Dedicated Admin Connection）か | Yes |
| LastQuery | string | 最後に実行されたSQLステートメント | Yes |

### 出力先

PowerShellパイプライン（SMO Process object）

## 処理フロー

### 処理シーケンス

```
1. processブロック: 各インスタンスに対して処理
   ├─ Connect-DbaInstanceで接続
   │
   ├─ [SQL 2005以降] DMVクエリ実行
   │     └─ dm_exec_connections + dm_exec_sessions + endpoints + dm_exec_sql_text
   │
   ├─ Server.EnumProcesses()でプロセス一覧取得
   │
   ├─ フィルタリング
   │     ├─ [Intersect] ANDで各条件を適用
   │     └─ [デフォルト] ORで各条件を適用（重複排除）
   │
   ├─ [ExcludeSystemSpids] SPID > 50 でフィルタ
   │
   └─ 各セッションに対して
         ├─ DMV結果とマージ（Add-Member）
         └─ Select-DefaultViewで出力
```

### フローチャート

```mermaid
flowchart TD
    A[開始] --> B{各SqlInstanceに対して}
    B --> C[Connect-DbaInstance]
    C --> D{接続成功?}
    D -->|No| E[Stop-Function]
    E --> B
    D -->|Yes| F{バージョン > 8?}
    F -->|Yes| G[DMVクエリ実行]
    F -->|No| H[DMV結果なし]
    G --> I[EnumProcesses]
    H --> I
    I --> J{Intersect?}
    J -->|Yes| K[ANDフィルタ]
    J -->|No| L[ORフィルタ]
    K --> M{ExcludeSystemSpids?}
    L --> M
    M -->|Yes| N[SPID > 50フィルタ]
    M -->|No| O[全セッション]
    N --> P{各セッションに対して}
    O --> P
    P --> Q[DMV結果とマージ]
    Q --> R[Select-DefaultView出力]
    R --> P
    P -->|完了| B
    B -->|完了| S[終了]
```

## ビジネスルール

### 業務ルール

| ルールNo | ルール名 | 内容 | 適用条件 |
|---------|---------|------|---------|
| BR-001 | フィルタ結合モード | Intersect指定でAND結合、未指定でOR結合 | フィルタ指定時 |
| BR-002 | SPID包含 | Spid指定時、ブロックしているSPIDも含める | Spid指定時 |
| BR-003 | システムSPID定義 | システムSPIDはSPID 1-50 | ExcludeSystemSpids時 |
| BR-004 | ステータス補完 | 空のStatusは'sleeping'に置換 | 常時 |
| BR-005 | コマンド補完 | 空のCommandは'AWAITING COMMAND'に置換 | 常時 |
| BR-006 | DMVバージョン制限 | DMVクエリはSQL Server 2005以降のみ実行 | 常時 |

### 計算ロジック

MinutesAsleep計算：
- `DATEDIFF(MINUTE, s.last_request_end_time, GETDATE())`

フィルタリングロジック：
- ORモード: 各条件に一致するセッションを追加（重複排除）
- ANDモード: 全セッションから各条件で絞り込み

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

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

| 操作 | 対象テーブル | 操作種別 | 概要 |
|-----|-------------|---------|------|
| 接続情報取得 | sys.dm_exec_connections | SELECT | 接続詳細情報取得 |
| セッション情報取得 | sys.dm_exec_sessions | SELECT | セッション詳細情報取得 |
| エンドポイント取得 | sys.endpoints | SELECT | エンドポイント情報取得 |
| クエリテキスト取得 | sys.dm_exec_sql_text | SELECT | SQLテキスト取得 |

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

#### sys.dm_exec_sessions + sys.dm_exec_connections + sys.endpoints

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| SELECT | s.session_id, s.host_process_id | セッション識別情報 | - |
| SELECT | s.login_time, s.client_version | タイミング情報 | - |
| SELECT | c.net_transport, c.encrypt_option, c.auth_scheme | 接続詳細 | - |
| SELECT | e.name, e.is_admin_endpoint | エンドポイント情報 | - |
| SELECT | t.text | 最後に実行されたクエリ | OUTER APPLY |

## エラー処理

### エラーケース一覧

| エラーコード | エラー種別 | 発生条件 | 対処方法 |
|------------|----------|---------|---------|
| - | 接続エラー | SQL Serverへの接続失敗 | Stop-Function (ConnectionError) で処理継続 |

### リトライ仕様

リトライ処理は実装されていません。

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

読み取り専用クエリのため、トランザクション管理は不要です。

## パフォーマンス要件

- EnumProcesses()とDMVクエリは数秒以内で完了
- フィルタリングはメモリ内で実行

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

- VIEW SERVER STATE権限が必要
- LastQueryにはセキュリティ上機密なSQLが含まれる可能性がある
- SqlCredentialで認証情報を安全に取り扱い

## 備考

- Michael J Swartのクエリ（https://sqlperformance.com/2017/07/sql-performance/find-database-connection-leaks）を参考
- Stop-DbaProcessコマンドでプロセスを終了可能

---

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

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

### 推奨読解順序

#### Step 1: DMVクエリを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaProcess.ps1 | `public/Get-DbaProcess.ps1` | 156-176行目: DMVクエリ定義 |

**読解のコツ**: dm_exec_connections, dm_exec_sessions, endpoints, dm_exec_sql_textの4つを結合している点に注目。

#### Step 2: フィルタリングロジックを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaProcess.ps1 | `public/Get-DbaProcess.ps1` | 188-230行目: Intersectモードとデフォルトモードのフィルタ |

**主要処理フロー**:
1. **188-209行目**: Intersectモード（AND結合）
2. **210-229行目**: デフォルトモード（OR結合）
3. **196行目**: Spid指定時はBlockingSpidも含める

#### Step 3: 出力生成を理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaProcess.ps1 | `public/Get-DbaProcess.ps1` | 244-281行目: Add-Memberでプロパティ追加 |

**主要処理フロー**:
- **246-255行目**: Status/Commandの補完処理
- **258行目**: DMV結果とSPIDでマッチング
- **260-279行目**: 各プロパティをAdd-Memberで追加
- **281行目**: Select-DefaultViewで出力

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

```
Get-DbaProcess
    │
    └─ process ブロック
           │
           └─ foreach ($instance in $SqlInstance)
                  │
                  ├─ Connect-DbaInstance
                  │      └─ [失敗時] Stop-Function
                  │
                  ├─ [Version > 8] $server.Query($sql)
                  │      └─ DMV結果取得
                  │
                  ├─ $server.EnumProcesses()
                  │
                  ├─ フィルタリング
                  │      ├─ [Intersect] Where-Object (AND)
                  │      └─ [デフォルト] Where-Object (OR + 重複排除)
                  │
                  ├─ [ExcludeSystemSpids] Where-Object (Spid > 50)
                  │
                  └─ foreach ($session in $allSessions)
                         │
                         ├─ Status/Command補完
                         ├─ DMV結果マッチング
                         ├─ Add-Member (18項目)
                         │
                         └─ Select-DefaultView
```

### データフロー図

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

SqlInstance ───────▶ Connect-DbaInstance
                            │
                            ├─ EnumProcesses() ──▶ プロセス一覧
                            │
                            └─ DMVクエリ ──▶ 追加情報
                                  │
                                  ▼
                           フィルタリング
                                  │
  Login フィルタ ─────────────────┤
  Spid フィルタ ──────────────────┤
  Hostname フィルタ ──────────────┤
  Program フィルタ ───────────────┤
  Database フィルタ ──────────────┘
                                  │
                                  ▼
                           マージ処理
                                  │
                                  ▼
                           Select-DefaultView ───────▶ パイプライン出力
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaProcess.ps1 | `public/Get-DbaProcess.ps1` | ソース | メイン処理 |
| Stop-DbaProcess.ps1 | `public/Stop-DbaProcess.ps1` | ソース | プロセス終了（関連） |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
| Select-DefaultView.ps1 | `private/functions/Select-DefaultView.ps1` | ソース | デフォルト表示制御 |
| Stop-Function.ps1 | `private/functions/flowcontrol/Stop-Function.ps1` | ソース | エラー処理 |
