sqlinsight-pro/docs/integration.md

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

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:

& "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:

"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_instance_paused	instance	1 for en instans, hvis overvågning er sat på pause (fra 1.3)
sqlinsight_build_info	version, rulepack	SQLInsight Pro-version og regelpakke

Fra 1.3 er instanser, der er fjernet under Servere og databaser, ikke med, og instanser sat på pause kun i sqlinsight_instance_paused: en pause udløser ingen alarm. GET /api/v1/instances udelader fjernede instanser og har paused for de øvrige.

Eksempel på alarm i Prometheus:

- 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
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 (kræver scope support:write for at skrive)
GET /api/v1/dynamics-ax/databases, …/grant-script, …/batch-jobs, …/batch-runs, …/number-sequences, …/recids, …/sequence-samples, …/blocking	Dynamics AX: genkendte AX-databaser med læseadgang og GRANT, batchjob og kørsler, nummerserier, RecId, målingerne bag prognoserne og AX-brugere bag blokering. AX-brugere og logins er [udeladt]; se dynamics-ax.md
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 (kræver scope config:write for at ændre)
GET/POST /api/v1/windows-servers, …/{id}, …/{id}/test, …/{id}/grant-script, …/{id}/performance, …/{id}/disks, …/{id}/services, …/{id}/events, …/{id}/tasks, GET /api/v1/server-findings	Windows-servere: CPU, hukommelse, diske med prognose, tjenester, hændelseslog, planlagte opgaver og deres fund: se windows-servere.md
GET/POST /api/v1/synthetic-checks, …/{id}, …/{id}/run, …/{id}/results	Syntetiske tjek: se syntetiske-tjek.md (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

"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, eller af Administratorer på webserveren, når den er tom).

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:

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:

"SQLInsight": {
  "Notifications": {
    "EventLog": { "Enabled": true, "Source": "SQLInsight Pro", "MinSeverity": "Medium" }
  }
}

Kilden registreres én gang som administrator:

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.