Søren Eggert Lundsteen Olsen
30d89acbd7
- /api/v1/findings gains status (active/resolved/all), from/to, database,
ruleId, category, sort and paging (limit + X-Continuation header; the
response stays an array). /findings/{id} with fix script and history.
- /rules (built-in, community, local) and /instances/{name}/rule-states.
- /reports and /reports/{driftsrapport|analyse|rettigheder} as JSON or PDF,
built from the same models as the pages and PDFs.
- Page data: analysis, top-sql, disks, configuration, privileges (one or
all instances) and wait types. Statement texts, logins, names and
service accounts are "[udeladt]" unless ApiIncludesSensitiveEvidence.
- OpenAPI at /api/v1/openapi.json; a test fails when an endpoint is
missing from it.
- API tokens get scopes ("read", "support:write"); the old form is read
only, and new-api-token takes --scope. Token names show as token:<name>.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
150 lines
8.6 KiB
Markdown
150 lines
8.6 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 |
|
||
| `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.
|