# 画面設計書 150-スピンロック統計

## 概要

本ドキュメントは、dbatools PowerShellモジュールにおけるSQL Serverスピンロック統計（Spinlock Statistics）取得機能の設計仕様を定義する。

### 本画面の処理概要

SQL Serverのsys.dm_os_spinlock_statsからスピンロック競合統計を取得し、内部同期メカニズムに関するパフォーマンス情報を提供する機能。スピンロックはSQL Serverが非常に短い待機でクリティカルセクションやメモリ構造を保護するために使用する軽量同期プリミティブである。

**業務上の目的・背景**：スピンロック競合は、高CPU使用率と低スループットとして現れる深刻なパフォーマンス問題を引き起こす可能性がある。一般的なスピンロック競合シナリオには、tempdb割り当てボトルネック、特定データベースオブジェクトへの過度の同時アクティビティ、またはSQL Server内部データ構造の問題が含まれる。本機能を使用することで、スピンロック競合の原因を特定できる。

**画面へのアクセス方法**：PowerShellコンソールまたはスクリプトから以下のコマンドを実行する。
- `Get-DbaSpinLockStatistic` - スピンロック統計の取得

**主要な操作・処理内容**：
1. スピンロック統計取得（Get-DbaSpinLockStatistic）：sys.dm_os_spinlock_statsから全スピンロックタイプの統計を取得

**画面遷移**：CLIベースのため画面遷移は存在しない。

**権限による表示制御**：VIEW SERVER STATE権限が必要。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 272 | Get-DbaSpinLockStatistic | 主機能 | スピンロック統計の取得 |

## 画面種別

コマンドラインインターフェース（CLI）/ PowerShell関数

## URL/ルーティング

```powershell
# スピンロック統計の取得
Get-DbaSpinLockStatistic -SqlInstance sql01

# 複数インスタンスから取得
Get-DbaSpinLockStatistic -SqlInstance sql2008, sqlserver2012

# パイプラインで取得
'sql2008','sqlserver2012' | Get-DbaSpinLockStatistic

# DataTableに変換
Get-DbaSpinLockStatistic -SqlInstance sql01 | ConvertTo-DbaDataTable
```

## 入出力項目

### Get-DbaSpinLockStatistic パラメータ

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

## 表示項目

### Get-DbaSpinLockStatistic 出力

| 項目名 | 型 | 説明 |
|--------|-----|------|
| ComputerName | string | SQL Serverホストのコンピュータ名 |
| InstanceName | string | SQL Serverインスタンス名 |
| SqlInstance | string | 完全インスタンス名 |
| SpinLockName | string | スピンロックタイプ名（例：LOCK_HASH, LOGCACHE_ACCESS） |
| Collisions | bigint | スレッドがスピンロックを待機した回数 |
| Spins | bigint | ロック取得までの合計スピンサイクル数 |
| SpinsPerCollision | bigint | 衝突あたりの平均スピン数（効率指標） |
| SleepTime | bigint | スピン使い果たし後のスリープ合計時間（ミリ秒） |
| Backoffs | bigint | リトライ前にバックオフした回数 |

## イベント仕様

### 1-スピンロック統計取得

**Get-DbaSpinLockStatistic 実行時**

1. Connect-DbaInstanceでSQL Serverに接続（MinimumVersion 10）
2. sys.dm_os_spinlock_statsを照会
3. 全スピンロックタイプの統計を取得
4. PSCustomObjectとして出力

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

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

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| スピンロック統計取得 | sys.dm_os_spinlock_stats | SELECT | DMV読み取りのみ |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 発生条件 |
|-------------|------|---------------|---------|
| MSG001 | エラー | "Failure" | SQL Server接続失敗 |

## 例外処理

| 例外条件 | 対応処理 |
|---------|---------|
| SQL Server接続失敗 | Stop-Functionでエラー記録、Continueで次インスタンスへ |

## 備考

- SQL Server 2008以上が必要（MinimumVersion 10）
- スピンロック統計は待機統計でSOS_SCHEDULER_YIELDやその他のCPU関連待機が見られる場合に重要
- 高いCollisions値はスピンロック競合を示す
- 高いSpinsPerCollision値は効率低下を示す
- Paul Randalの高度なパフォーマンストラブルシューティング方法論に基づく
- 一般的なスピンロック競合シナリオ：tempdb割り当てボトルネック、特定オブジェクトへの過度の同時アクセス

---

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

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

### 推奨読解順序

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

スピンロック統計の出力構造を理解することが重要。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | Get-DbaSpinLockStatistic.ps1 | `public/Get-DbaSpinLockStatistic.ps1` | 49-64行目: .OUTPUTSセクション |
| 1-2 | Get-DbaSpinLockStatistic.ps1 | `public/Get-DbaSpinLockStatistic.ps1` | 118-128行目: PSCustomObject生成 |

**読解のコツ**: スピンロック統計には、Collisions（衝突回数）、Spins（スピン回数）、SpinsPerCollision（衝突あたりスピン数）、SleepTime（スリープ時間）、Backoffs（バックオフ回数）の5つの主要メトリクスがある。

#### Step 2: SQLクエリを理解する

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | Get-DbaSpinLockStatistic.ps1 | `public/Get-DbaSpinLockStatistic.ps1` | 96-103行目: $sqlクエリ定義 |

**主要処理フロー**:
- **96-103行目**: sys.dm_os_spinlock_statsから全カラムを取得

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

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | Get-DbaSpinLockStatistic.ps1 | `public/Get-DbaSpinLockStatistic.ps1` | 86-92行目: パラメータ定義 |
| 3-2 | Get-DbaSpinLockStatistic.ps1 | `public/Get-DbaSpinLockStatistic.ps1` | 112行目: MinimumVersion 10 |
| 3-3 | Get-DbaSpinLockStatistic.ps1 | `public/Get-DbaSpinLockStatistic.ps1` | 117-129行目: クエリ実行と出力 |

**主要処理フロー**:
- **112行目**: Connect-DbaInstance -MinimumVersion 10（SQL Server 2008以上）
- **117行目**: $server.Query($sql)でクエリ実行
- **118-128行目**: PSCustomObject作成

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

```
Get-DbaSpinLockStatistic
    │
    ├─ Test-FunctionInterrupt
    │
    ├─ Connect-DbaInstance -MinimumVersion 10
    │
    ├─ $server.Query()
    │      │
    │      └─ sys.dm_os_spinlock_stats
    │             ├─ name
    │             ├─ collisions
    │             ├─ spins
    │             ├─ spins_per_collision
    │             ├─ sleep_time
    │             └─ backoffs
    │
    └─ [foreach row]
           │
           └─ PSCustomObject
                  ├─ ComputerName
                  ├─ InstanceName
                  ├─ SqlInstance
                  ├─ SpinLockName
                  ├─ Collisions
                  ├─ Spins
                  ├─ SpinsPerCollision
                  ├─ SleepTime
                  └─ Backoffs
```

### データフロー図

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

SqlInstance ───────▶ Connect-DbaInstance ───▶ SMO Server
                     -MinimumVersion 10
                              │
                              ▼
                     sys.dm_os_spinlock_stats
                     照会
                              │
                              ├─ name
                              ├─ collisions
                              ├─ spins
                              ├─ spins_per_collision
                              ├─ sleep_time
                              └─ backoffs
                              │
                              ▼                          PSCustomObject
                     [foreach row]                       │
                              │                          ├─ SpinLockName
                              ▼                          ├─ Collisions
                     PSCustomObject出力                  ├─ Spins
                                                        ├─ SpinsPerCollision
                                                        ├─ SleepTime
                                                        └─ Backoffs
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| Get-DbaSpinLockStatistic.ps1 | `public/Get-DbaSpinLockStatistic.ps1` | ソース | スピンロック統計取得 |
