# 通知設計書 14-New-DbaAgentAlert

## 概要

本ドキュメントは、SQL Serverエージェントアラートを作成するdbatools PowerShellコマンド「New-DbaAgentAlert」の設計仕様を記載します。

### 本通知の処理概要

New-DbaAgentAlertは、SQL Server Agentに新しいアラートを作成し、特定のエラー重大度、メッセージID、パフォーマンス条件、またはWMIイベントを監視する自動通知システムを構築するコマンドです。

**業務上の目的・背景**：SQL Serverの安定稼働には、重大なエラーやパフォーマンス低下を即座に検知し、DBAに通知する仕組みが不可欠です。本コマンドにより、重大度レベル（17-25の致命的エラー）、特定のエラーメッセージ（823-825のディスクI/Oエラーなど）、パフォーマンス閾値超過、Windows WMIイベントに対するアラートを簡単に設定できます。

**通知の送信タイミング**：本コマンドは「アラートを作成する」コマンドであり、作成されたアラートが実際にトリガーされると、設定されたオペレーターに通知が送信されます。オペレーターへの通知方法はEmail、Pager、NetSendから選択可能です。

**通知の受信者**：アラート作成の結果はコマンド実行者に返されます。作成されたアラートが将来トリガーされた場合、-Operatorパラメータで指定されたオペレーターが通知を受け取ります。

**通知内容の概要**：アラートトリガー時には、SQL Serverエラーの詳細、NotificationMessageパラメータで指定されたカスタムメッセージ、およびイベント説明が通知されます。

**期待されるアクション**：管理者はアラートを作成後、テスト環境でトリガー条件を発生させて通知が正しく機能することを確認します。本番環境では、アラート発報時にDBAが迅速に問題を調査・対処することが期待されます。

## 通知種別

SQL Server Agent Alert（オペレーターへのEmail/Pager/NetSend通知を設定）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（アラート作成は即座に完了） |
| 優先度 | 低（ConfirmImpact = 'Low'） |
| リトライ | 無（作成失敗時はエラーメッセージ出力） |

### 送信先決定ロジック

- Operatorパラメータ：通知を受け取るSQL Server Agentオペレーターを指定
- NotifyMethodパラメータ：通知方法（None/NotifyEmail/Pager/NetSend/NotifyAll）を指定
- DelayBetweenResponsesパラメータ：通知スパム防止のための間隔（秒）を設定

## 通知テンプレート

### コンソール出力の場合

| 項目 | 内容 |
|-----|------|
| 出力形式 | Microsoft.SqlServer.Management.Smo.Agent.Alert |
| 確認プロンプト | ShouldProcess による確認（ConfirmImpact = 'Low'） |

### 本文テンプレート

```
アラート作成成功時の出力:
ComputerName         : {ComputerName}
SqlInstance          : {SqlInstance}
InstanceName         : {InstanceName}
Name                 : {AlertName}
ID                   : {AlertID}
JobName              : {JobName}
AlertType            : {EventAlert/ErrorNumberAlert/PerformanceConditionAlert/WmiEventAlert}
CategoryName         : {CategoryName}
Severity             : {0-25}
MessageId            : {MessageId}
IsEnabled            : {True/False}
DelayBetweenResponses: {Seconds}
```

### 添付ファイル

| ファイル名 | 形式 | 条件 | 説明 |
|----------|------|------|------|
| なし | - | - | 本コマンドは添付ファイルを出力しない |

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| Alert | アラート名 | パラメータ指定 | Yes |
| Category | アラートカテゴリ | パラメータ指定 | No |
| Database | 対象データベース | パラメータ指定 | No |
| Operator | 通知先オペレーター | パラメータ指定 | No |
| DelayBetweenResponses | 通知間隔（秒） | パラメータ指定（デフォルト60） | No |
| Disabled | 無効状態で作成 | パラメータ指定 | No |
| EventDescriptionKeyword | イベント説明キーワード | パラメータ指定 | No |
| EventSource | イベントソース | パラメータ指定 | No |
| JobId | 応答ジョブID | パラメータ指定 | No |
| Severity | 重大度レベル（0-25） | パラメータ指定 | No |
| MessageId | メッセージID | パラメータ指定 | No |
| NotificationMessage | カスタム通知メッセージ | パラメータ指定 | No |
| PerformanceCondition | パフォーマンス条件 | パラメータ指定 | No |
| WmiEventNamespace | WMI名前空間 | パラメータ指定 | No |
| WmiEventQuery | WMIクエリ | パラメータ指定 | No |
| NotifyMethod | 通知方法 | パラメータ指定（デフォルトNotifyAll） | No |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| コマンド実行 | New-DbaAgentAlert実行 | 同名アラート未存在 | 新規アラートを作成 |
| パイプライン入力 | SqlInstanceのパイプ入力 | 複数インスタンス対応 | 複数サーバーに一括作成 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| 同名アラート存在 | 既存アラートがある場合はStop-Functionでスキップ |
| -WhatIf指定時 | 実際の作成は行わず、処理内容のみ表示 |
| AG Listener経由 | 可用性グループリスナー経由では作成不可 |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[コマンド実行開始] --> B[foreach instance in SqlInstance]
    B --> C[Connect-DbaInstance]
    C --> D{接続成功?}
    D -->|No| E[Stop-Function: 接続エラー]
    E --> B
    D -->|Yes| F{同名アラート存在?}
    F -->|Yes| G[Stop-Function: 既存アラート]
    G --> B
    F -->|No| H{ShouldProcess確認}
    H -->|No| I[スキップ]
    I --> B
    H -->|Yes| J[New-Object Alert]
    J --> K{AG Listener?}
    K -->|Yes| L[Stop-Function: AG Listenerエラー]
    L --> B
    K -->|No| M[プロパティ設定ループ]
    M --> N[Create実行]
    N --> O{Operator指定?}
    O -->|Yes| P[AddNotification実行]
    P --> Q[Alter実行]
    O -->|No| R[JobServer.Refresh]
    Q --> R
    R --> S[Get-DbaAgentAlert出力]
    S --> T{次のインスタンス?}
    T -->|Yes| B
    T -->|No| U[終了]
```

## データベース参照・更新仕様

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| msdb.dbo.sysalerts | 既存アラートの重複チェック | SMO経由で参照 |

### テーブル別参照項目詳細

#### msdb.dbo.sysalerts

| 参照項目（カラム名） | 用途 | 取得条件 |
|-------------------|------|---------|
| name | 重複チェック | 作成前に同名存在確認 |

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| msdb.dbo.sysalerts | INSERT | 新規アラートの作成 |
| msdb.dbo.sysnotifications | INSERT | オペレーター通知設定の追加 |

#### sysalertsテーブル

| 操作 | 項目（カラム名） | 更新値 | 備考 |
|-----|-----------------|-------|------|
| INSERT | name | Alert パラメータ | アラート名 |
| INSERT | severity | Severity パラメータ | 重大度（0-25） |
| INSERT | message_id | MessageId パラメータ | メッセージID |
| INSERT | delay_between_responses | DelayBetweenResponses | 応答間隔 |
| INSERT | enabled | !Disabled | 有効フラグ |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 接続失敗 | SqlInstanceに接続不可 | Stop-Function -Continue |
| 既存アラート | 同名アラートが存在 | Stop-Function -Continue |
| AG Listener | リスナー経由でのアクセス | Stop-Function -Continue（プライマリレプリカへの接続を推奨） |
| Create失敗 | SMO Create()失敗 | Stop-Function -Continue |
| AddNotification失敗 | オペレーター通知追加失敗 | Stop-Function -Continue |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（リトライなし） |
| リトライ間隔 | - |
| リトライ対象エラー | - |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | なし |
| 1日あたり上限 | なし |

### 配信時間帯

制限なし（任意のタイミングで実行可能）

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

- sysadmin権限が必要
- SqlCredentialパラメータによりSQL Server認証、Windows認証、AD認証をサポート
- 可用性グループリスナー経由では実行不可（プライマリレプリカに直接接続が必要）
- PagerとNetSend通知方法は将来バージョンで廃止予定

## 備考

- MessageIdとSeverityは排他的な条件（MessageId指定時はSeverityは0に設定される）
- DelayBetweenResponsesのデフォルト値は60秒
- NotifyMethodのデフォルト値はNotifyAll
- JobIdは00000000-0000-0000-0000-000000000000（空GUID）がデフォルト
- アラート作成後、Get-DbaAgentAlertを呼び出して結果を出力

---

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

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

### 推奨読解順序

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

まず、作成されるAlertオブジェクトの構造とパラメータを理解することが重要です。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | New-DbaAgentAlert.ps1 | `public/New-DbaAgentAlert.ps1` | 108-142行目: .OUTPUTSセクションで出力プロパティを確認 |
| 1-2 | New-DbaAgentAlert.ps1 | `public/New-DbaAgentAlert.ps1` | 161-185行目: パラメータ定義 |

**読解のコツ**: 多数のパラメータがあるが、必須は`SqlInstance`と`Alert`（アラート名）のみ。Severity/MessageId/PerformanceCondition/WmiEventのいずれかを指定してアラート種別を決定する。

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

処理の起点となるパラメータ設定を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | New-DbaAgentAlert.ps1 | `public/New-DbaAgentAlert.ps1` | 160行目: CmdletBinding（ConfirmImpact = 'Low'） |
| 2-2 | New-DbaAgentAlert.ps1 | `public/New-DbaAgentAlert.ps1` | 186-202行目: processブロック冒頭の変数設定 |

**主要処理フロー**:
1. **187-189行目**: NotifyMethod を IncludeEventDescription に設定
2. **199-201行目**: MessageId指定時はSeverityを0に設定

#### Step 3: 接続と重複チェックを理解する

SQL Server接続と既存アラートの重複チェックを確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | New-DbaAgentAlert.ps1 | `public/New-DbaAgentAlert.ps1` | 203-208行目: 接続処理 |
| 3-2 | New-DbaAgentAlert.ps1 | `public/New-DbaAgentAlert.ps1` | 210-212行目: 既存アラートチェック |

**主要処理フロー**:
- **204-207行目**: Connect-DbaInstance による接続とエラーハンドリング
- **211行目**: `$server.JobServer.Alerts.Name` で既存アラート名を確認

#### Step 4: アラート作成処理を理解する

SMOを使用したアラート作成処理を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 4-1 | New-DbaAgentAlert.ps1 | `public/New-DbaAgentAlert.ps1` | 217-226行目: Alertオブジェクト作成とAG Listenerチェック |
| 4-2 | New-DbaAgentAlert.ps1 | `public/New-DbaAgentAlert.ps1` | 227-235行目: プロパティ設定ループ |
| 4-3 | New-DbaAgentAlert.ps1 | `public/New-DbaAgentAlert.ps1` | 237行目: Create()実行 |

**主要処理フロー**:
- **218行目**: `New-Object Microsoft.SqlServer.Management.Smo.Agent.Alert` でSMOオブジェクト作成
- **220-225行目**: AG Listener経由の場合のエラーハンドリング
- **227行目**: 設定可能なプロパティリストの定義
- **229-235行目**: 変数の値をSMOプロパティに設定
- **237行目**: `$newalert.Create()` でデータベースに永続化

#### Step 5: オペレーター通知設定を理解する

作成したアラートへの通知設定追加を確認します。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 5-1 | New-DbaAgentAlert.ps1 | `public/New-DbaAgentAlert.ps1` | 239-249行目: AddNotification処理 |

**主要処理フロー**:
- **240行目**: Operatorパラメータが指定されている場合のみ実行
- **243行目**: `$newalert.AddNotification()` でオペレーターに通知を追加
- **244行目**: `$newalert.Alter()` で変更を永続化

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

```
New-DbaAgentAlert (エントリーポイント)
    |
    └── [processブロック]
            |
            ├── 変数設定
            |       ├── NotifyMethod → IncludeEventDescription
            |       ├── Category → CategoryName
            |       ├── Database → DatabaseName
            |       └── MessageId指定時 → Severity = 0
            |
            └── foreach ($instance in $SqlInstance)
                    |
                    ├── Connect-DbaInstance
                    |
                    └── foreach ($name in $Alert)
                            |
                            ├── 重複チェック ($server.JobServer.Alerts.Name)
                            |
                            ├── ShouldProcess確認
                            |
                            ├── New-Object Alert
                            |       └── AG Listener チェック
                            |
                            ├── プロパティ設定ループ
                            |       └── CategoryName, DatabaseName, etc.
                            |
                            ├── Create()
                            |
                            ├── AddNotification (Operator指定時)
                            |       └── Alter()
                            |
                            ├── JobServer.Refresh()
                            |
                            └── Get-DbaAgentAlert 出力
```

### データフロー図

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

SqlInstance ──────────┐
SqlCredential ────────┤
Alert ────────────────┤
Category ─────────────┤
Database ─────────────┤
Operator ─────────────┼──▶ Connect-DbaInstance ──▶ $server
DelayBetweenResponses─┤                               │
Disabled ─────────────┤                               ▼
Severity ─────────────┤                    既存アラート重複チェック
MessageId ────────────┤                               │
PerformanceCondition──┤                               ▼
WmiEventNamespace ────┤                    New-Object Alert
WmiEventQuery ────────┤                               │
NotifyMethod ─────────┘                               ▼
                                           プロパティ設定
                                                      │
                                                      ▼
                                           Create()
                                                      │
                                                      ▼
                                           AddNotification (Optional)
                                                      │
                                                      ▼
                                           Get-DbaAgentAlert
                                                      │
                                                      ▼
                                Microsoft.SqlServer.Management.Smo.Agent.Alert
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| New-DbaAgentAlert.ps1 | `public/New-DbaAgentAlert.ps1` | ソース | メインコマンド実装 |
| Get-DbaAgentAlert.ps1 | `public/Get-DbaAgentAlert.ps1` | ソース | 作成結果の取得（内部呼び出し） |
| Connect-DbaInstance.ps1 | `public/Connect-DbaInstance.ps1` | ソース | SQL Server接続 |
| Stop-Function.ps1 | `private/functions/Stop-Function.ps1` | ソース | エラー処理ユーティリティ |
| Write-Message.ps1 | `private/functions/Write-Message.ps1` | ソース | ログ出力ユーティリティ |
