feat: add metrics, observability, test fixtures, and scaling playbook artifacts

scripts/loadtest/README.md

@@ -0,0 +1,90 @@
+# Load Test Scaffolding
+
+These files back the scaling/performance playbook.
+
+## WebSocket chat
+
+Run with an explicit WebSocket URL, for example:
+
+```bash
+WS_URL=wss://linearvoid.tv/ws?username=loadtest&room=main npx artillery run scripts/loadtest/ws-chat.yml
+```
+
+Capture output to an artifact file for the worksheet:
+
+```bash
+WS_URL=wss://linearvoid.tv/ws?username=loadtest&room=main npx artillery run scripts/loadtest/ws-chat.yml --output artifacts/ws-chat-report.json
+```
+
+PowerShell equivalent:
+
+```powershell
+$env:WS_URL = 'wss://linearvoid.tv/ws?username=loadtest&room=main'
+New-Item -ItemType Directory -Force artifacts | Out-Null
+npx artillery run scripts/loadtest/ws-chat.yml --output artifacts/ws-chat-report.json
+```
+
+Summarize key counters, rates, and available percentile stats from a saved Artillery JSON report:
+
+```powershell
+pwsh -File scripts/loadtest/summarize-artillery.ps1 -ReportFile artifacts/ws-chat-report.json
+```
+
+## Admin API
+
+Run with a cookie or session header that can access admin endpoints:
+
+```bash
+ADMIN_BASE_URL=https://linearvoid.tv ADMIN_SESSION_COOKIE="session=..." k6 run scripts/loadtest/admin-api.js
+```
+
+Capture machine-readable metrics and a text summary:
+
+```bash
+ADMIN_BASE_URL=https://linearvoid.tv ADMIN_SESSION_COOKIE="session=..." k6 run --summary-export artifacts/admin-api-summary.json scripts/loadtest/admin-api.js > artifacts/admin-api-output.txt
+```
+
+PowerShell equivalent:
+
+```powershell
+$env:ADMIN_BASE_URL = 'https://linearvoid.tv'
+$env:ADMIN_SESSION_COOKIE = 'session=...'
+New-Item -ItemType Directory -Force artifacts | Out-Null
+k6 run --summary-export artifacts/admin-api-summary.json scripts/loadtest/admin-api.js | Tee-Object -FilePath artifacts/admin-api-output.txt
+```
+
+The script emits global and per-endpoint thresholds (overview, analytics, chat-log, users) so p95 and error-rate regressions are visible per route.
+
+Summarize endpoint p95 and failure rates from a saved k6 JSON summary:
+
+```powershell
+pwsh -File scripts/loadtest/summarize-k6.ps1 -SummaryFile artifacts/admin-api-summary.json
+```
+
+## PowerShell helper
+
+Use the helper to run one scenario or both and automatically write outputs into a dated artifact folder:
+
+- The helper resolves scenario paths from its own script location, so it can be run from any current working directory.
+- WebSocket runs also emit `ws-chat-summary.txt` with connection/error counters and available summary percentiles.
+- Admin runs also emit `admin-api-endpoint-summary.txt` with per-endpoint p95/error values.
+
+```powershell
+pwsh -File scripts/loadtest/run-loadtests.ps1 -Scenario ws -WsUrl 'wss://linearvoid.tv/ws?username=loadtest&room=main'
+```
+
+```powershell
+pwsh -File scripts/loadtest/run-loadtests.ps1 -Scenario admin -AdminBaseUrl 'https://linearvoid.tv' -AdminSessionCookie 'session=...'
+```
+
+```powershell
+pwsh -File scripts/loadtest/run-loadtests.ps1 -Scenario all -WsUrl 'wss://linearvoid.tv/ws?username=loadtest&room=main' -AdminBaseUrl 'https://linearvoid.tv' -AdminSessionCookie 'session=...'
+```
+
+## Notes
+
+- Adjust target URLs for test lab or production.
+- Keep the same commit SHA or image tag when comparing runs.
+- Record results using the worksheet in `docs/operations/scaling-performance-playbook.md`.
+- Store raw outputs under an `artifacts/` folder per run date (for example `artifacts/2026-08-09/`).
+- The repository `.gitignore` excludes benchmark artifacts by default.