# 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, lange og store transaktioner, 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 /api/v1/instances/{navn}/activity` | Åbne brugertransaktioner (alder, log, database) og sætninger, der har kørt over grænsen, lige nu. Login, vært, program og sætning er `[udeladt]` |
| `GET /api/v1/instances/{navn}/tempdb` | tempdb's størrelse og fri plads, version store med udvikling og de databaser, der laver versioner, ældste snapshot-transaktion og største forbrugere |
| `GET /api/v1/instances/{navn}/error-log?days=7` | Vigtige hændelser i fejlloggen (1–90 dage), kilde og dækning. Eksemplet er `[udeladt]`; se [fejllog.md](fejllog.md) |
| `GET /api/v1/instances/{navn}/replication` | Replikering set fra distributøren: hver distributionsagents status, seneste kørsel og forsinkelse, og fejl det seneste døgn |
| `GET /api/v1/instances/{navn}/index-usage?days=30` | Læsninger og skrivninger pr. index summeret over dagene (1–400), på tværs af genstarter, mindst læste først |
| `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`/`POST /api/v1/monitored-instances`, `…/{id}`, `…/{id}/connection-test`, `…/{id}/discovery`, `…/{id}/databases`, `…/{id}/grant-script`, `POST /api/v1/instance-discovery`, `GET /api/v1/agent-requests/{id}` | Hvilke servere og databaser der overvåges, forbindelsestest, søgning og GRANT-script: se [servere-og-databaser.md](servere-og-databaser.md#api) (kræver scope `config:write` for at ændre) |
| `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. Scopes: `read`, `support:write` (supportsager) og `config:write` (hvilke servere og databaser der overvåges; for Windows-brugere kræver det medlemskab af `SQLInsight:Web:AdminGroups`).

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.