# 画面設計書 166-ログイン監視

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるログイン監視機能（Watch-DbaDbLogin）の画面設計書です。複数のSQL Serverインスタンスのアクティブな接続を監視し、クライアント詳細を中央のトラッキングテーブルに記録する機能を提供します。

### 本画面の処理概要

**業務上の目的・背景**：サーバーマイグレーションやアプリケーション更新を計画する際、「誰がどこからどのデータベースに接続しているか」という情報は極めて重要ですが、多くの場合ドキュメント化が不十分です。本機能は、接続アクティビティを数週間にわたって記録することで、忘れられたアプリケーションの発見、接続文字列の検証、実際のデータベース使用パターンの把握を可能にします。

**画面へのアクセス方法**：PowerShellコマンドラインから `Watch-DbaDbLogin` コマンドレットを実行してアクセスします。5-10分ごとにスケジュール実行することを推奨します。

**主要な操作・処理内容**：
1. Central Management Server（CMS）またはテキストファイルからサーバーリストを取得
2. 各SQL Serverのsys.dm_exec_sessions/requestsをクエリ
3. ローカルサーバー接続とシステムデータベース接続を除外
4. 接続情報を中央データベースのトラッキングテーブルに挿入

**画面遷移**：本機能は単独のコマンドレットとして動作し、データベーステーブルへの書き込みを行います。

**権限による表示制御**：監視対象サーバーでsysadmin権限が必要です（最も正確な結果を得るため）。格納先データベースへの書き込み権限が必要です。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 588 | Watch-DbaDbLogin | 主機能 | ログインの監視 |
| 432 | Get-DbaRegServer | 内部呼出 | CMSからのサーバーリスト取得 |
| 327 | Connect-DbaInstance | 内部呼出 | SQL Serverインスタンスへの接続 |

## 画面種別

CLI（コマンドラインインターフェース）- 監視・記録

## URL/ルーティング

PowerShellコマンド: `Watch-DbaDbLogin`

## 入出力項目

### 入力パラメータ

| パラメータ名 | 型 | 必須 | 説明 |
|-------------|-----|------|------|
| SqlInstance | DbaInstance | No | データ格納先SQL Serverインスタンス |
| SqlCredential | PSCredential | No | SQL Server認証用の資格情報 |
| Database | string | No | データ格納先データベース |
| Table | string | No | データ格納先テーブル（デフォルト: "DbaTools-WatchDbLogins"） |
| SqlCms | string | No* | 監視対象サーバーを取得するCMS |
| ServersFromFile | string | No* | 監視対象サーバーリストのファイルパス |
| InputObject | Microsoft.SqlServer.Management.Smo.Server[] | No* | パイプラインからの事前接続サーバー |
| EnableException | switch | No | 例外を有効化 |

*SqlCms、ServersFromFile、InputObjectのいずれかが必須

### データベースへの出力項目

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | 監視対象サーバーのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全なSQL Serverインスタンス名 |
| LoginTime | DateTime | セッションのログイン日時 |
| Login | string | ログイン名 |
| Host | string | クライアントホスト名 |
| Program | string | クライアントアプリケーション名 |
| DatabaseId | int | データベースID |
| Database | string | 接続先データベース名 |
| IsSystem | bit | システムセッションフラグ |
| CaptureTime | DateTime | 情報取得日時 |

## 表示項目

本機能はデータベーステーブルに直接書き込み、パイプラインへの出力は行いません。進行状況はWrite-Messageで通知されます。

## イベント仕様

### 1-コマンド実行

1. **パラメータ検証**（行111-114）: SqlCms/ServersFromFile/InputObjectのいずれかが必須
2. **格納先接続**（行116-121）: Connect-DbaInstanceで格納先サーバーに接続
3. **サーバーリスト取得**（行129-144）: CMS/ファイルからサーバーリスト取得
4. **各サーバー接続**（行149-159）: 各監視対象サーバーに接続
5. **セッション情報取得**（行164-200）: DMVクエリでセッション情報取得
6. **データ書き込み**（行207-210）: Write-DbaDbTableDataでテーブルに書き込み

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| セッション情報取得 | sys.dm_exec_sessions | SELECT | 監視対象サーバーのセッション情報 |
| セッション情報取得 | sys.dm_exec_requests | SELECT | リクエスト情報（結合） |
| データ書き込み | {Database}.dbo.{Table} | INSERT | 接続情報の記録 |

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

#### {指定テーブル}（DbaTools-WatchDbLogins）

| 操作 | 項目（カラム名） | 更新値・取得条件 | 備考 |
|-----|-----------------|-----------------|------|
| INSERT | ComputerName | $instance.ComputerName | サーバーから取得 |
| INSERT | InstanceName | $instance.ServiceName | サーバーから取得 |
| INSERT | SqlInstance | $instance.DomainInstanceName | サーバーから取得 |
| INSERT | LoginTime | s.login_time | DMVから取得 |
| INSERT | Login | s.login_name | DMVから取得 |
| INSERT | Host | s.host_name | DMVから取得 |
| INSERT | Program | s.program_name | DMVから取得 |
| INSERT | DatabaseId | DB_ID() | DMVから取得 |
| INSERT | Database | DB_NAME() | DMVから取得 |
| INSERT | IsSystem | ~s.is_user_process | DMVから取得 |
| INSERT | CaptureTime | GETDATE() | 記録時点 |

## メッセージ仕様

| メッセージタイプ | 条件 | メッセージ内容 |
|-----------------|------|---------------|
| Error | 入力元未指定 | "You must specify a server list source using -SqlCms or -ServersFromFile or pipe in connected instances." |
| Error | 接続失敗 | "Failure" - ConnectionError |
| Error | CMSアクセス失敗 | "The CMS server, {SqlCms}, was not accessible." |
| Error | ファイル未発見 | "{ServersFromFile} was not found." |
| Warning | 非sysadmin | "Not a sysadmin on {instance}, resultset would be underwhelming. Skipping." |
| Output | 書き込み成功 | "Added process information for {instance} to datatable." |
| Verbose | データなし | "No data returned for {instance}." |

## 例外処理

| 例外条件 | 処理内容 |
|---------|---------|
| 入力元パラメータなし | Stop-Functionでエラーメッセージを出力して終了 |
| SQL Server接続失敗 | Stop-Functionでエラーを記録し、次のサーバーの処理を継続 |
| 非sysadmin | 警告メッセージを出力してスキップ |
| CMSアクセス失敗 | Stop-Functionでエラーを出力して終了 |
| ファイル未発見 | Stop-Functionでエラーを出力して終了 |

## 備考

- 5-10分ごとにスケジュール実行することで、数週間にわたる接続パターンを把握可能
- ローカルサーバー接続（Host = ComputerName）は自動的に除外
- システムデータベース（master/msdb/model/tempdb）接続は除外
- SSMS Query、SQL Managementプログラムは除外
- sysadmin権限がない場合、取得できる情報が制限されるためスキップ
- -AutoCreateTableオプションによりテーブルが存在しない場合は自動作成

---

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

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

### 推奨読解順序

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

格納先テーブルの構造と取得するセッション情報を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Watch-DbaDbLogin.ps1 | `public/Watch-DbaDbLogin.ps1` | 行65-68の.OUTPUTSセクション |

**読解のコツ**: パイプライン出力はなく、データベーステーブルへの直接書き込みを行う点に注目。

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

パラメータ検証とサーバーリスト取得を理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Watch-DbaDbLogin.ps1 | `public/Watch-DbaDbLogin.ps1` | 行94-108のパラメータ定義 |
| 2-2 | Watch-DbaDbLogin.ps1 | `public/Watch-DbaDbLogin.ps1` | 行111-114のパラメータ検証 |

**主要処理フロー**:
1. **行111-114**: SqlCms/ServersFromFile/InputObjectの入力チェック
2. **行116-121**: 格納先サーバーへの接続
3. **行129-144**: CMSまたはファイルからサーバーリスト取得

#### Step 3: サーバー接続とセッション情報取得を理解する

各サーバーへの接続とDMVクエリを理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Watch-DbaDbLogin.ps1 | `public/Watch-DbaDbLogin.ps1` | 行149-159のサーバー接続ループ |
| 3-2 | Watch-DbaDbLogin.ps1 | `public/Watch-DbaDbLogin.ps1` | 行171-200のDMVクエリ（SQL 2008/2012+） |

**主要処理フロー**:
- **行166-169**: sysadminチェック（Test-SqlSa）
- **行171-200**: バージョン別のDMVクエリ実行
- **行204-206**: ローカル接続とシステムDB除外

#### Step 4: データ書き込み処理を理解する

データの変換と書き込みを理解します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | Watch-DbaDbLogin.ps1 | `public/Watch-DbaDbLogin.ps1` | 行207-210のWrite-DbaDbTableData呼び出し |

**主要処理フロー**:
- **行208**: Select-Objectでカラムを整形
- **行208**: ConvertTo-DbaDataTableでDataTable変換
- **行208**: Write-DbaDbTableData -AutoCreateTableで書き込み

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

```
Watch-DbaDbLogin
    |
    +-- パラメータ検証 (行111-114)
    |
    +-- Connect-DbaInstance [格納先] (行117)
    |       └── 格納先サーバーへの接続
    |
    +-- Get-DbaRegServer (行131) [CMSの場合]
    |       └── 登録済みサーバー取得
    |
    +-- Get-Content (行139) [ファイルの場合]
    |       └── テキストファイル読み込み
    |
    +-- [各サーバーのループ]
    |       |
    |       +-- Connect-DbaInstance (行152-154)
    |       |       └── 監視対象サーバーへの接続
    |       |
    |       +-- Test-SqlSa (行166)
    |       |       └── sysadmin権限チェック
    |       |
    |       +-- $instance.Query() (行204)
    |       |       └── DMVクエリ実行
    |       |
    |       └── Write-DbaDbTableData (行208)
    |               └── データ書き込み
    |
    └── Write-Message (行210, 212)
            └── 結果通知
```

### データフロー図

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

SqlCms ─────────────────┐
                        │
ServersFromFile ────────┼──> サーバーリスト取得
                        │         │
InputObject ────────────┘         v
                               [サーバーリスト]
                                    │
                                    v
                        ┌──> Connect-DbaInstance (各サーバー)
                        │         │
                        │         v
                        │    Test-SqlSa (権限チェック)
                        │         │
                        │         v
                        │    DMVクエリ実行
                        │         │
                        │         v
                        │    フィルタリング
                        │    (ローカル/システムDB除外)
                        │         │
                        │         v
                        └──> ConvertTo-DbaDataTable
                                    │
                                    v
                        Write-DbaDbTableData ──────> [テーブル]
                                                    {Database}.{Table}
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Watch-DbaDbLogin.ps1 | `public/Watch-DbaDbLogin.ps1` | ソース | ログイン監視の実装 |
| Get-DbaRegServer.ps1 | `public/Get-DbaRegServer.ps1` | ソース | CMSサーバーリスト取得 |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続処理 |
| Write-DbaDbTableData.ps1 | `public/Write-DbaDbTableData.ps1` | ソース | テーブルへのデータ書き込み |
| ConvertTo-DbaDataTable.ps1 | `public/ConvertTo-DbaDataTable.ps1` | ソース | DataTable変換 |
