# 画面設計書 132-ネットワークアクティビティ

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるSQL Serverホストコンピュータのネットワークトラフィック統計取得機能の設計仕様を定義する。

### 本画面の処理概要

SQL Serverホストコンピュータのネットワークインターフェースに関するリアルタイムのトラフィック統計を取得・表示する機能を提供する。

**業務上の目的・背景**：SQL Serverのパフォーマンス問題を診断する際、ネットワーク帯域の飽和がボトルネックとなっている可能性を調査する必要がある。特に大規模なデータ転送、バックアップ操作、レプリケーショントラフィックが集中する環境では、ネットワーク帯域の監視が重要となる。本機能は、各ネットワークインターフェースのスループットをリアルタイムで確認し、帯域使用率と容量を比較することで、ネットワーク関連のパフォーマンス問題を特定する。

**画面へのアクセス方法**：PowerShellコンソールから以下のコマンドを実行してアクセスする
- `Get-DbaNetworkActivity -ComputerName <コンピュータ名>`

**主要な操作・処理内容**：
1. 指定されたコンピュータのネットワーク名を解決
2. CIMセッションを確立（WSMan優先、失敗時DCom使用）
3. Win32_PerfFormattedData_Tcpip_NetworkInterfaceクラスからパフォーマンスデータを取得
4. 各ネットワークインターフェースの送受信バイト数、合計帯域を表示
5. インターフェースの最大帯域幅を人間が読みやすい形式（10Gb, 1Gb等）で表示

**画面遷移**：CLIベースのため画面遷移は存在しない。パイプラインによる他のコマンドとの連携が可能。

**権限による表示制御**：対象コンピュータに対するローカル管理者権限が必要。CIM/WMIへのリモートアクセス権限が必要となる。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 367 | Get-DbaNetworkActivity | 主機能 | ネットワークアクティビティの取得 |
| - | Resolve-DbaNetworkName | 補助機能 | コンピュータ名の解決 |

## 画面種別

CLI（コマンドラインインターフェース）

## URL/ルーティング

該当なし（PowerShellコマンドレット）

## 入出力項目

### Get-DbaNetworkActivity

| 項目名 | データ型 | 必須 | 説明 |
|--------|----------|------|------|
| ComputerName | string[] | いいえ | 対象コンピュータ名（デフォルト: ローカルコンピュータ）|
| Credential | PSCredential | いいえ | 接続に使用する資格情報 |
| EnableException | switch | いいえ | 例外を直接発生させるかどうか |

## 表示項目

### Get-DbaNetworkActivity 出力（デフォルトビュー）

| 項目名 | データ型 | 説明 |
|--------|----------|------|
| ComputerName | string | コンピュータ名 |
| NIC | string | ネットワークインターフェース名（Nameプロパティのエイリアス） |
| BytesReceivedPersec | uint64 | 1秒あたりの受信バイト数 |
| BytesSentPersec | uint64 | 1秒あたりの送信バイト数 |
| BytesTotalPersec | uint64 | 1秒あたりの合計バイト数 |
| Bandwidth | string | インターフェースの帯域幅容量（10Gb/1Gb/100Mb/10Mb/1Mb/100Kb/Low） |

### 追加プロパティ（Select-Object * で取得可能）

| 項目名 | データ型 | 説明 |
|--------|----------|------|
| CurrentBandwidth | uint64 | 帯域幅（ビット/秒） |
| OutputQueueLength | uint32 | 送信キュー長 |
| PacketsReceivedPersec | uint64 | 1秒あたりの受信パケット数 |
| PacketsSentPersec | uint64 | 1秒あたりの送信パケット数 |
| PacketsOutboundErrors | uint64 | 送信エラー数 |
| PacketsReceivedErrors | uint64 | 受信エラー数 |
| PacketsReceivedDiscarded | uint64 | 破棄された受信パケット数 |
| PacketsOutboundDiscarded | uint64 | 破棄された送信パケット数 |

## イベント仕様

### 1-Get-DbaNetworkActivity実行

1. ComputerNameパラメータからインスタンス名部分を除去し、一意のコンピュータ名リストを作成
2. 各コンピュータに対してResolve-DbaNetworkNameで完全修飾ドメイン名を取得
3. WSManプロトコルでCIMセッションを作成を試行
4. WSManが失敗した場合、DComプロトコルでCIMセッションを作成
5. Win32_PerfFormattedData_Tcpip_NetworkInterfaceクラスからデータを取得
6. 各NICにComputerNameとBandwidthプロパティを追加
7. デフォルトビューで結果を出力

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

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

本機能はWindowsパフォーマンスカウンターを読み取り専用で参照するため、データベースやシステムへの更新は発生しない。

| 操作（イベント） | 対象 | 操作種別 | 概要 |
|----------------|------|---------|------|
| Get-DbaNetworkActivity | Win32_PerfFormattedData_Tcpip_NetworkInterface | SELECT | パフォーマンスカウンターの読み取り |

## メッセージ仕様

| メッセージID | 種別 | メッセージ | 発生条件 |
|-------------|------|----------|----------|
| - | Warning | Can't create CIMSession on {computer} | WSManとDCom両方でCIMセッション作成失敗 |
| - | Warning | can't connect to {computer} | コンピュータへの接続失敗（名前解決失敗） |
| - | Verbose | Creating CIMSession on {computer} over WSMan | WSManでCIMセッション作成時 |
| - | Verbose | Creating CIMSession on {computer} over DCom | DComでCIMセッション作成時 |
| - | Verbose | Getting properties for Network Interfaces on {computer} | NIC情報取得時 |

## 例外処理

| 例外条件 | 処理内容 |
|----------|----------|
| コンピュータ名解決失敗 | 警告メッセージを表示し、次のコンピュータへ継続 |
| WSMan CIMセッション作成失敗 | DComプロトコルでリトライ |
| DCom CIMセッション作成失敗 | 警告メッセージを表示し、次のコンピュータへ継続 |

## 備考

- 帯域幅の表示は以下のしきい値で分類される：
  - 10000000000 bps = 10Gb
  - 1000000000 bps = 1Gb
  - 100000000 bps = 100Mb
  - 10000000 bps = 10Mb
  - 1000000 bps = 1Mb
  - 100000 bps = 100Kb
  - その他 = Low
- 複数のコンピュータをパイプラインで渡すことが可能
- 返却されるのはポイントインタイムのスナップショットであり、継続的な監視ではない

---

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

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

### 推奨読解順序

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

まず、出力されるオブジェクトの構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaNetworkActivity.ps1 | `public/Get-DbaNetworkActivity.ps1` | .OUTPUTSセクションで出力オブジェクトの構造を確認（行35-57） |

**読解のコツ**: Win32_PerfFormattedData_Tcpip_NetworkInterfaceは標準的なWindowsパフォーマンスカウンタークラスであり、追加プロパティとしてComputerNameとBandwidthが動的に追加される。

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

処理の起点となる関数の構造を特定。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaNetworkActivity.ps1 | `public/Get-DbaNetworkActivity.ps1` | begin/processブロックの構造 |

**主要処理フロー**:
1. **行87**: ComputerNameからインスタンス名部分を除去
2. **行88**: DComセッションオプションの作成

#### Step 3: メイン処理フローを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaNetworkActivity.ps1 | `public/Get-DbaNetworkActivity.ps1` | processブロック内のforeachループ |

**主要処理フロー**:
- **行91-92**: 各コンピュータの処理開始、Resolve-DbaNetworkNameによる名前解決
- **行93-94**: FullComputerNameが取得できた場合の処理
- **行95-96**: WSManでのCIMセッション作成試行
- **行97-100**: WSMan失敗時のDComフォールバック
- **行101-106**: CIMセッション成功時のNIC情報取得
- **行103**: Get-CimInstanceでパフォーマンスデータ取得
- **行104**: ComputerNameスクリプトプロパティの追加
- **行105**: Bandwidthスクリプトプロパティの追加（switch文による帯域幅分類）
- **行106**: Select-DefaultViewで表示プロパティを設定

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

```
Get-DbaNetworkActivity
    |
    +-- ComputerName処理
    |       +-- Split("\")[0] でインスタンス名除去
    |       +-- Select-Object -Unique で重複排除
    |
    +-- foreach ($computer in $ComputerName)
            |
            +-- Resolve-DbaNetworkName
            |       +-- FullComputerName取得
            |
            +-- New-CimSession (WSMan)
            |       |
            |       +-- 失敗時: New-CimSession (DCom)
            |
            +-- Get-CimInstance
            |       +-- Win32_PerfFormattedData_Tcpip_NetworkInterface
            |
            +-- Add-Member (ComputerName, Bandwidth)
            |
            +-- Select-DefaultView
```

### データフロー図

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

ComputerName ────────▶ Split("\")[0] ───────────────▶ ホスト名のみ
    |                        |
    v                        v
              ┌─────────────────────────────────┐
              │     Resolve-DbaNetworkName      │
              └─────────────────────────────────┘
                             |
                             v
              ┌─────────────────────────────────┐
              │   New-CimSession (WSMan/DCom)   │
              └─────────────────────────────────┘
                             |
                             v
              ┌─────────────────────────────────┐
              │         Get-CimInstance         │
              │  Win32_PerfFormattedData_Tcpip_ │
              │       NetworkInterface          │
              └─────────────────────────────────┘
                             |
                             v
              ┌─────────────────────────────────┐
              │  Add-Member (ComputerName,      │
              │            Bandwidth)           │
              └─────────────────────────────────┘
                             |
                             v
              ┌─────────────────────────────────┐    ┌──────────────────┐
              │       Select-DefaultView        │───▶│  NIC統計オブジェクト │
              └─────────────────────────────────┘    └──────────────────┘
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaNetworkActivity.ps1 | `public/Get-DbaNetworkActivity.ps1` | ソース | ネットワークアクティビティ取得メインコマンド |
| Resolve-DbaNetworkName.ps1 | `public/Resolve-DbaNetworkName.ps1` | ソース | ネットワーク名解決ユーティリティ |
