Søren Eggert Lundsteen Olsen
f3551b1bf0
- POST/GET /api/v1/support-cases[/{id}] and POST .../{id}/close in
SQLInsight Web, sharing the /support form's logic: same checks, finding
prefill without sensitive evidence, Idempotency-Key as the request id,
202 Accepted with Location, problem+json 403 without the support:write
scope or a support license. RequestedBy is the Windows user or
token:<name>.
- Closing: "Luk sag" on /support and the API record CloseRequested
(migration 0012, column-level UPDATE for the read-only web login); the
agent sends it to the hub with backoff and sets Closed when confirmed;
a pending case is closed once it has a number; an older hub list never
turns CloseRequested back to Open.
- Hub: POST /api/v1/cases/{reference}/close for the license's own cases
(others 404), idempotent, ClosedBy/ClosedComment (EF migration
CaseClosedBy). Portal closing records "SEOSoft: <user>"; the customer
page shows who closed and why; the support report and CSV get "Lukket af".
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
151 lines
8.8 KiB
Markdown
151 lines
8.8 KiB
Markdown
# Integration med eksisterende overvågning
|
||
|
||
SQLInsight Pro kan levere data til de værktøjer, driften allerede bruger:
|
||
|
||
| Værktøj | Sådan |
|
||
|---|---|
|
||
| Prometheus og Grafana | `/metrics` i webbrugerfladen, og et færdigt Grafana-dashboard |
|
||
| Scripts, ITSM, egne dashboards | JSON-API under `/api/v1/` |
|
||
| System Center Operations Manager (SCOM) og andre, der læser Windows' hændelseslog | Agenten skriver hændelser med faste event-id'er |
|
||
| Teams, mail og webhooks | Se notifikationer i [installation.md](installation.md) |
|
||
|
||
Alt er skrivebeskyttet: intet af det kan ændre noget i SQLInsight Pro eller på jeres SQL Servere.
|
||
|
||
## API-tokens
|
||
|
||
Brugere logger ind i webbrugerfladen med Windows-login. Maskiner som Prometheus kan i stedet bruge et token:
|
||
|
||
```powershell
|
||
& "C:\Program Files\SQLInsight\Web\SQLInsight.Web.exe" new-api-token prometheus
|
||
```
|
||
|
||
Kommandoen skriver selve tokenet (gem det i Prometheus) og en linje til `appsettings.json`:
|
||
|
||
```json
|
||
"SQLInsight": {
|
||
"Web": {
|
||
"ApiTokens": { "prometheus": "sha256:4F1C…" }
|
||
}
|
||
}
|
||
```
|
||
|
||
Kun tokenets SHA-256 gemmes i konfigurationen. Et token giver kun adgang til `/api/` og `/metrics`, aldrig til websiderne. Fjern linjen for at tilbagekalde tokenet. Windows-login virker også på API'et.
|
||
|
||
## Prometheus og Grafana
|
||
|
||
`deploy/prometheus/prometheus.yml` viser scrape-konfigurationen. Tokenet lægges i en fil, som `credentials_file` peger på. Hent data højst hvert minut; agenten måler selv med sine egne intervaller.
|
||
|
||
| Metric | Labels | Betydning |
|
||
|---|---|---|
|
||
| `sqlinsight_instance_up` | instance | 1, hvis seneste kontakt lykkedes inden for 10 minutter |
|
||
| `sqlinsight_instance_last_seen_timestamp_seconds` | instance | Tidspunkt for seneste vellykkede kontakt |
|
||
| `sqlinsight_instance_info` | instance, version, level, edition | Version og CU-niveau (værdi 1) |
|
||
| `sqlinsight_findings` | instance, severity | Antal aktive fund pr. alvor |
|
||
| `sqlinsight_rule_findings` | instance, rule, severity | Antal aktive fund pr. regel |
|
||
| `sqlinsight_rules_not_measurable` | instance | Regler, der ikke kunne vurderes |
|
||
| `sqlinsight_metric` | instance, metric | Seneste måling: `cpu.sqlserver`, `cpu.other` (%), `memory.ple` (s), `memory.grants_pending`, `workload.batch_requests`, `workload.compilations` (pr. s), `connections.user`, `blocking.processes` |
|
||
| `sqlinsight_build_info` | version, rulepack | SQLInsight Pro-version og regelpakke |
|
||
|
||
Eksempel på alarm i Prometheus:
|
||
|
||
```yaml
|
||
- alert: SqlInsightCriticalFinding
|
||
expr: sqlinsight_findings{severity="critical"} > 0
|
||
for: 5m
|
||
annotations:
|
||
summary: "{{ $labels.instance }} har {{ $value }} kritiske fund i SQLInsight Pro"
|
||
```
|
||
|
||
**Grafana:** importér `deploy/grafana/sqlinsight-dashboard.json` (Dashboards → New → Import) og vælg jeres Prometheus-datakilde. Dashboardet viser instanser, der er nede, fund pr. alvor, CPU, page life expectancy, batch requests, fund pr. regel og versioner.
|
||
|
||
## JSON-API
|
||
|
||
Alt, hvad webbrugerfladen viser, kan hentes som JSON under `/api/v1/` med de samme tidsrum og filtre, og rapporterne også som PDF. API'et er beskrevet i OpenAPI på `GET /api/v1/openapi.json` (samme login som API'et), som fx Postman, Power BI eller en kodegenerator kan læse. Tider er ISO 8601 (UTC eller med tidszone), fx `2026-10-01T08:00:00Z`.
|
||
|
||
| Kald | Svar |
|
||
|---|---|
|
||
| `GET /api/v1/instances` | Instanser med version, seneste kontakt, `up` og antal fund pr. alvor |
|
||
| `GET /api/v1/findings` | Fund. Filtre: `status=active\|resolved\|all` (standard active), `from`/`to` (opstået for aktive, løst for løste, begge for all), `instance`, `database` (emnet nævner databasen), `ruleId`, `minSeverity=Info\|Low\|Medium\|High\|Critical`, `category` (fx `SEC` i SQLI-SEC-001), `sort=severity\|firstSeen\|lastSeen\|resolved`, `limit` (1–1000, standard 100). Er der flere, står værdien til `?continuation=` i svar-headeren `X-Continuation` |
|
||
| `GET /api/v1/findings/{id}` | Ét fund med forklaring, anbefaling, målinger, fix-script, referencer og historik (først/sidst set, løst) |
|
||
| `GET /api/v1/rules` | Alle regler med id, titel, kategori og kilde (`indbygget`, `community`, `lokal`) |
|
||
| `GET /api/v1/instances/{navn}/rule-states` | Hver regels udfald på instansen: `passed`, `findings`, `notMeasurable`, `notApplicable`, `error`, med årsag |
|
||
| `GET /api/v1/reports` | Rapporttyperne og deres parametre |
|
||
| `GET /api/v1/reports/driftsrapport?days=30&format=json\|pdf` | Driftsrapporten: nøgletal, sammenfatning, kontroller pr. instans, instanser, aktive fund, konfigurationsændringer |
|
||
| `GET /api/v1/reports/analyse?instance=…&from=…&to=…&sort=cpu&format=json\|pdf` | Analyse af et tidsrum (som siden og PDF'en) |
|
||
| `GET /api/v1/reports/rettigheder?days=90&instance=…&format=json\|pdf` | Rettighedsrevisionen for én eller alle instanser |
|
||
| `GET /api/v1/instances/{navn}/analysis?from=&to=&sort=` | Analyse af tidsrum: målinger med vurdering, ventetider, tungeste sætninger med aktivitet, diske, blocking, deadlocks, langvarige operationer, fund |
|
||
| `GET /api/v1/instances/{navn}/top-sql?from=&to=&sort=cpu\|varighed\|laesninger\|koersler&limit=` | Tungeste sætninger i et tidsrum (standard seneste døgn) |
|
||
| `GET /api/v1/instances/{navn}/disks?from=&to=` | Diskhastighed pr. drev med vurdering og tidsserier |
|
||
| `GET /api/v1/instances/{navn}/configuration?days=90` | Opsætning, tjenester, tempdb, sp_configure, trace flags og ændringslog |
|
||
| `GET /api/v1/instances/{navn}/privileges?days=90` | Rettigheder med udfoldede Windows-grupper, sa, adgangskodepolitik, default trace og ændringer |
|
||
| `GET /api/v1/privileges?days=90` | Det samme for alle instanser |
|
||
| `GET /api/v1/instances/{navn}/wait-types/{ventetype}?from=&to=` | Forklaring, udvikling og de sætninger, der ventede |
|
||
| `POST /api/v1/support-cases`, `GET /api/v1/support-cases[/{id}]`, `POST /api/v1/support-cases/{id}/close` | Supportsager: se [support.md](support.md) (kræver scope `support:write` for at skrive) |
|
||
| `GET /metrics` | Prometheus-format |
|
||
|
||
**Følsomme data:** forespørgselstekster, logins, personnavne, værts- og programnavne og tjenestekonti vises som `[udeladt]`, medmindre `SQLInsight:Web:ApiIncludesSensitiveEvidence` er `true`. Det gælder både fund, rapporter i JSON og sidernes data. PDF-rapporterne indeholder de samme data som i webbrugerfladen.
|
||
|
||
**Tokens og scopes:** et token i den gamle form (`"navn": "sha256:…"`) må kun læse (`read`). Et token med flere rettigheder skrives som
|
||
|
||
```json
|
||
"ApiTokens": { "itsm": { "hash": "sha256:…", "scopes": [ "read", "support:write" ] } }
|
||
```
|
||
|
||
og oprettes med `SQLInsight.Web.exe new-api-token itsm --scope read,support:write`. Windows-brugere med adgang til webbrugerfladen må det samme som i webbrugerfladen.
|
||
|
||
PowerShell:
|
||
|
||
```powershell
|
||
$h = @{ Authorization = "Bearer $token" }
|
||
Invoke-RestMethod "https://sqlinsight.domæne.local/api/v1/findings?minSeverity=High" -Headers $h
|
||
Invoke-WebRequest "https://sqlinsight.domæne.local/api/v1/reports/driftsrapport?days=30&format=pdf" -Headers $h -OutFile driftsrapport.pdf
|
||
|
||
# Alle løste fund det seneste kvartal, side for side
|
||
$url = "https://sqlinsight.domæne.local/api/v1/findings?status=resolved&from=$((Get-Date).AddDays(-90).ToString('o'))&limit=500"
|
||
$all = @(); $next = $null
|
||
do {
|
||
$r = Invoke-WebRequest ($url + $(if ($next) { "&continuation=$next" })) -Headers $h
|
||
$all += $r.Content | ConvertFrom-Json
|
||
$next = $r.Headers['X-Continuation']
|
||
} while ($next)
|
||
```
|
||
|
||
curl:
|
||
|
||
```bash
|
||
curl -H "Authorization: Bearer $TOKEN" "https://sqlinsight.domæne.local/api/v1/instances/AX01%5CAX30/top-sql?sort=cpu&limit=10"
|
||
```
|
||
|
||
**Power BI og Excel:** Hent data → Fra internettet → Avanceret, angiv URL'en (fx `/api/v1/findings?status=all&limit=1000`) og en HTTP-header `Authorization` med værdien `Bearer <token>`. Brug et token med kun `read`.
|
||
|
||
## SCOM og Windows' hændelseslog
|
||
|
||
Slå kanalen til i agentens `appsettings.json`:
|
||
|
||
```json
|
||
"SQLInsight": {
|
||
"Notifications": {
|
||
"EventLog": { "Enabled": true, "Source": "SQLInsight Pro", "MinSeverity": "Medium" }
|
||
}
|
||
}
|
||
```
|
||
|
||
Kilden registreres én gang som administrator:
|
||
|
||
```powershell
|
||
New-EventLog -LogName Application -Source "SQLInsight Pro"
|
||
```
|
||
|
||
Hændelserne skrives i loggen **Application**:
|
||
|
||
| Event-id | Niveau | Hændelse |
|
||
|---|---|---|
|
||
| 1004 | Error | Nyt kritisk fund |
|
||
| 1003 | Error | Nyt fund med høj alvor |
|
||
| 1002 | Warning | Nyt fund med middel alvor |
|
||
| 1001 / 1000 | Information | Nyt fund med lav alvor / info |
|
||
| 2000 | Information | Fund løst |
|
||
| 3000 | Error | Instansen kan ikke nås |
|
||
| 3001 | Information | Instansen svarer igen |
|
||
|
||
Beskeden starter med en overskrift og har derefter én linje pr. felt (`Instans:`, `Regel:`, `Emne:`, `Alvor:`, `Beskrivelse:`, `Link:`). I SCOM oprettes en regel eller monitor af typen *Windows Event* på kilden `SQLInsight Pro` med de event-id'er, der skal give alarm. Brug fx 1004 og 3000 til alarm og 2000 og 3001 til at lukke den igen. Hændelsesloggen er ikke omfattet af loftet over notifikationer pr. time, så ingen hændelser går tabt.
|