Søren Eggert Lundsteen Olsen
cd72f14883
docs/dynamics-ax.md: detection, the optional read access per version, how AX is read (SELECT only, TOP, 2 s lock timeout or snapshot, never NOLOCK), the rules SQLI-AX-001..010 with thresholds, batch times and the unverified AX 3.0 STATUS mapping, forecasts from SQLInsight's own samples, AX users behind blocking (CONTEXT_INFO, honest for 3.0), the hub opt-in, the API and how to drop in a real 2009/2012 schema. AX 2009/2012/F&O are marked as based on Microsoft's documented schema, not verified against customer data. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
121 lines
12 KiB
Markdown
121 lines
12 KiB
Markdown
# Dynamics AX
|
||
|
||
Fra version 1.4 overvåger SQLInsight Pro Microsoft Dynamics AX-databaser specifikt: batchjob, nummerserier, RecId og hvilken AX-bruger der står bag en blokering. Det findes under **Dynamics AX** i menuen (vises, så snart en overvåget database er genkendt som AX) og i API'et under `/api/v1/dynamics-ax/`.
|
||
|
||
> **Hvor sikre er vi på skemaet?** Axapta 3.0 er bygget og testet mod en rigtig kundedatabase ([`schema-ax30.tsv`](dynamics-ax/schema-ax30.tsv): tabeller ejet af `bmssa`, 32-bit RECID, `BATCH` med lokal `STARTDATE` + `STARTTIME` i sekunder efter midnat). **AX 4.0, AX 2009, AX 2012 og Dynamics 365 F&O er baseret på Microsofts dokumenterede skema – ikke verificeret mod kundedata.** Det dokumenterede skema står i [`schema-ax2009.documented.tsv`](dynamics-ax/schema-ax2009.documented.tsv) og [`schema-ax2012.documented.tsv`](dynamics-ax/schema-ax2012.documented.tsv). Leverer en kunde det rigtige skema (se [nedenfor](#nyt-kundeskema)), lægges det ind som `schema-ax2009.tsv`/`schema-ax2012.tsv`, og testene kører så mod det i stedet.
|
||
|
||
## Genkendelse
|
||
|
||
En database er AX, når systemtabellerne `SQLDICTIONARY` og `DATAAREA` ligger i samme skema. Versionen afgøres af skemaet ét sted ([`AxDetection.cs`](../src/SQLInsight.Core/DynamicsAx/AxDetection.cs)), som bruges af *Servere og databaser*, AX-collectorerne, community-reglerne `COM-AX-*` og webbrugerfladen:
|
||
|
||
| Kendetegn | Version |
|
||
|---|---|
|
||
| `SQLDICTIONARY.RECID` er `int` (præcision 10) | Axapta 2.5/3.0 (kan ikke skelnes; typisk skema `bmssa`) |
|
||
| `bigint`, ingen `BATCHJOB` | AX 4.0 |
|
||
| `BATCHJOB`, ingen `NUMBERSEQUENCESCOPE` | AX 2009 |
|
||
| `NUMBERSEQUENCESCOPE`, ingen `PARTITION`-kolonne | AX 2012 RTM/FP |
|
||
| `PARTITION` og modeldatabasen `<db>_model` på instansen | AX 2012 R2/R3 |
|
||
| `PARTITION`, intet modellager | Dynamics 365 F&O on-premises (formodet) |
|
||
|
||
Genkendelsen læser kun metadata (`sys.tables`, `sys.columns`, `HAS_PERMS_BY_NAME`) og kræver ikke mere end [`grant-least-privilege.sql`](../db/permissions/grant-least-privilege.sql). Den kører hver time i de databaser, der er valgt til overvågning. **AX-tjek kører kun i databaser, der er genkendt som AX og valgt til overvågning**; de generelle tjek kører i alle valgte databaser som hidtil.
|
||
|
||
## Valgfri læseadgang til AX-tabellerne
|
||
|
||
Batchjob, nummerserier og RecId kræver `SELECT` på nogle få AX-systemtabeller – aldrig kundedata (debitorer, ordrer, posteringer) og aldrig skriverettigheder:
|
||
|
||
| Version | Tabeller |
|
||
|---|---|
|
||
| Axapta 3.0 og AX 4.0 | `BATCH`, `NUMBERSEQUENCETABLE`, `NUMBERSEQUENCEREFERENCE`, `SYSTEMSEQUENCES`, `SQLDICTIONARY`, `DATAAREA` |
|
||
| AX 2009 | `BATCHJOB`, `BATCHJOBHISTORY`, `NUMBERSEQUENCETABLE`, `NUMBERSEQUENCEREFERENCE`, `SYSTEMSEQUENCES`, `SQLDICTIONARY`, `DATAAREA` |
|
||
| AX 2012 og F&O | som AX 2009 plus `NUMBERSEQUENCESCOPE` |
|
||
|
||
Adgangen er et tilvalg pr. database. **Dynamics AX → AX-databaser** viser for hver database, hvilke tabeller agenten må læse, og de nøjagtige `GRANT`-sætninger med skema (`bmssa` i AX 3.0) og agentens login udfyldt. Det samme for enhver AX-database: [`db/permissions/grant-dynamics-ax-read.sql`](../db/permissions/grant-dynamics-ax-read.sql), som selv finder version og skema (fjernes igen med [`revoke-dynamics-ax-read.sql`](../db/permissions/revoke-dynamics-ax-read.sql)). SQLInsight kører aldrig scripts selv.
|
||
|
||
Uden adgangen er tjekket **ikke målbart**, og årsagen er den nøjagtige `GRANT`, der mangler – aldrig en fejl.
|
||
|
||
## Sådan læser SQLInsight AX
|
||
|
||
- **Kun SELECT**, kun på standardtabellerne ovenfor, og aldrig i kundens database ud over det: al historik (batchkørsler, målinger af nummerserier) gemmes i SQLInsights eget repository.
|
||
- **Begrænset:** `TOP` på hver forespørgsel (1000 batchjob, 1000 historikrækker, de 5000 mest brugte nummerserier, de 500 højeste RecId-serier), og historikken læses efter RECID, som AX altid har et unikt indeks på.
|
||
- **Uden at vente på AX:** `READ COMMITTED` med `SET LOCK_TIMEOUT 2000` – er en række låst, opgiver læsningen efter 2 sekunder og prøver igen næste gang (det forrige billede beholdes, så fund ikke blinker). Har databasen `ALLOW_SNAPSHOT_ISOLATION`, bruges `SNAPSHOT`; med `READ_COMMITTED_SNAPSHOT` læses versioner. **Aldrig `NOLOCK`.**
|
||
- **Uden at skifte database:** forespørgslerne køres i AX-databasen med `[db].sys.sp_executesql`.
|
||
- **Kolonnetjek først:** hver forespørgsel bygges ud fra de kolonner, databasen faktisk har. Mangler en nødvendig kolonne, er tjekket "ikke målbart" med den præcise kolonne; mangler en valgfri, udelades den med en note.
|
||
- **SQL Server 2005 og nyere.** På SQL Server 2000 (legacy ODBC) genkendes AX under *Servere og databaser*, men datatjekkene kører ikke.
|
||
|
||
Den præcise SQL for hver regel står i [`SQL Scripts/`](../SQL%20Scripts/) (fx `SQLI-AX-003.sql`), genereret fra koden og klar til at køre i SSMS.
|
||
|
||
## Regler
|
||
|
||
| Regel | Hvad | Tærskel (`SQLInsight:DynamicsAx`) |
|
||
|---|---|---|
|
||
| SQLI-AX-001 | Batchjob er endt med fejl (nu, eller seneste kørsel af et gentaget job) | `BatchFailedLookbackHours` = 24 |
|
||
| SQLI-AX-002 | Batchjob kører længere end normalt, målt mod jobbets egne seneste kørsler | `BatchLongRunningFactor` = 2 × 90 %-fraktilen, mindst `BatchLongRunningMinimumMinutes` = 10, efter `BatchHistoryMinimumRuns` = 5 kørsler |
|
||
| SQLI-AX-003 | Batchjob er ikke startet til tiden; efter et døgn "aldrig startet" | `BatchLateMinutes` = 30, `BatchNeverStartedHours` = 24 |
|
||
| SQLI-AX-004 | Batchjob hænger i Udfører | `BatchStuckHours` = 6 (medmindre jobbet normalt kører så længe) |
|
||
| SQLI-AX-005 | Nummerserie er ved at løbe tør, nu eller efter prognosen | `NumberSequenceWarnPercent` = 80, `NumberSequenceCriticalPercent` = 95, `ForecastWarnDays` = 90, `ForecastCriticalDays` = 30 |
|
||
| SQLI-AX-006 | Nummerseriens format har færre cifre end Højeste kræver | – |
|
||
| SQLI-AX-007 | Spærret nummerserie bruges stadig af en reference | – |
|
||
| SQLI-AX-008 | Kontinuerlig nummerserie er ikke ryddet op | 7 dage eller 2 × seriens interval |
|
||
| SQLI-AX-009 | RecId er ved at løbe tør – Axapta 3.0's 32-bit RecId advares langt tidligere | `RecId32WarnPercent` = 50, `RecId32CriticalPercent` = 75, `RecId32ForecastDays` = 730; 64-bit: `RecId64WarnPercent` = 80 |
|
||
| SQLI-AX-010 | AX-bruger blokerer andre | `BlockingSeconds` = 30 |
|
||
|
||
Tærsklerne sættes i agentens `appsettings.json`:
|
||
|
||
```json
|
||
"SQLInsight": {
|
||
"DynamicsAx": { "BatchLateMinutes": 30, "BatchStuckHours": 6, "NumberSequenceWarnPercent": 80, "ForecastWarnDays": 90 }
|
||
}
|
||
```
|
||
|
||
De eksisterende community-regler `COM-AX-001` til `-007` (support, SQL Server-version, MAXDOP, RecId-indeks, heaps, statistikker) læser kun metadata og kører nu også kun i genkendte og valgte AX-databaser.
|
||
|
||
### Batchjob
|
||
|
||
Planlagt start er `BATCHJOB.ORIGSTARTDATETIME` (UTC) i AX 2009 og senere, og `BATCH.STARTDATE` + `STARTTIME` (lokal tid, sekunder efter midnat) i Axapta 3.0 og AX 4.0; de lokale tider regnes om til UTC med SQL Servers aktuelle forskel mellem `GETDATE()` og `GETUTCDATE()` (en kørsel lige over et sommertidsskift kan derfor ligge en time ved siden af).
|
||
|
||
Hvert jobs historik er SQLInsights egen (`insight.AxBatchRuns`, gemt `EventDays` = 90 dage): i AX 2009 og senere fra `BATCHJOBHISTORY`, læst efter RECID; Axapta 3.0 og 4.0 gemmer ingen historik, så SQLInsight registrerer selv de kørsler, den ser blive afsluttet (kørselstiden måles fra første gang, den så jobbet køre, og korte kørsler, der starter og slutter mellem to målinger, kommer ikke med). Et job i Axapta 3.0 er klasse + firma + batchgruppe, fordi AX 3.0 laver en ny række for hver gentagelse.
|
||
|
||
**`STATUS` i Axapta 3.0 er ikke verificeret mod kundedata.** SQLInsight antager 0 Venter, 1 Udfører, 2 Fejl, 3 Afsluttet, 4 Tilbageholdt. Siden *Batchjob* viser de rå værdier, der findes, så de kan sammenlignes med batchlisten i AX. AX 2009 og senere følger Microsofts dokumenterede `BatchStatus` (0 Tilbageholdt, 1 Venter, 2 Udfører, 3 Fejl, 4 Afsluttet, 5 Klar, 6 Ikke kørt, 7 Annullerer, 8 Annulleret).
|
||
|
||
### Nummerserier og RecId
|
||
|
||
Forbrug = (`NEXTREC` − `LOWEST`) i forhold til `HIGHEST` – eller formatets kapacitet (10^antal `#` − 1), hvis den er lavere. Prognoserne bygger på SQLInsights egne målinger: én pr. serie pr. dag af `NEXTREC` og `SYSTEMSEQUENCES.NEXTVAL` (`insight.AxSequenceSamples`, gemt `HourlyDays` = 400 dage). Forbruget pr. dag regnes fra den ældste måling inden for `ForecastBasisDays` (30) dage, der er mindst et døgn gammel; prognosen kommer altså tidligst et døgn efter, at læseadgangen er givet. Manuelle og cykliske serier får ingen prognose.
|
||
|
||
RecId-grænsen er typens maksimum – `int` (2.147.483.647) når `NEXTVAL` er `int` som i Axapta 3.0, ellers `bigint` – eller `MAXVAL`, hvis den er sat lavere. I Axapta 3.0 er RecId pr. tabel og firma.
|
||
|
||
### AX-brugere bag blokering
|
||
|
||
Alle AX-brugere går gennem AOS'ens login. **AX 2009 og 2012** (og F&O) kan skrive AX-brugeren og AX-sessionen i sessionens `CONTEXT_INFO`, når `connectioncontext` er slået til i AOS-konfigurationen (registreringsdatabasen på AOS-serveren; kræver genstart af AOS). SQLInsight læser den fra blokeringsmålingerne (første ord med bogstaver = bruger, første tal = AX-session; formatet er Microsofts for AX 2012 og ikke verificeret mod kundedata). **Axapta 3.0 og AX 4.0 sætter aldrig `CONTEXT_INFO`**: brugeren kan ikke ses fra SQL Server, og SQLInsight siger det og viser vært (AOS'en ved 3-lags-installation, brugerens pc ved 2-lags-klient) og program. AX-brugeren er en følsom oplysning.
|
||
|
||
## SQLInsight Hub
|
||
|
||
AX-fund (`SQLI-AX-*` og `COM-AX-*`) sendes kun til SQLInsight Hub for databaser, hvor *AX-fund til SQLInsight Hub* er slået til under [Servere og databaser](servere-og-databaser.md#dynamics-ax-fund-og-sqlinsight-hub) (standard fra). Hvert fund bærer databasen i sit emne (`database: AX30 · batch: …`), så det følger databasens valg. AX-reglernes udfald sendes kun, når mindst én database har valget slået til, og deres årsag (som kan nævne tabeller, logins og GRANT-tekst) erstattes af en fast tekst. AX-brugere er følsomme og sendes kun med `SendSensitiveEvidence`.
|
||
|
||
## API
|
||
|
||
| Endpoint | Indhold |
|
||
|---|---|
|
||
| `GET /api/v1/dynamics-ax/databases` | Genkendte AX-databaser: version, verificeret, skema, modeldatabase, firmaer, læseadgang pr. tabel, manglende tabeller og GRANT |
|
||
| `GET /api/v1/dynamics-ax/grant-script?instance=&database=` | GRANT-sætningerne og hele `grant-dynamics-ax-read.sql` udfyldt for databasen |
|
||
| `GET /api/v1/dynamics-ax/batch-jobs` | Batchjob nu: status, planlagt/faktisk start, forsinkelse, kørselstid, median og 90 %-fraktil, rå STATUS-værdier |
|
||
| `GET /api/v1/dynamics-ax/batch-runs?database=&job=&days=7` | Afsluttede kørsler fra repository'et |
|
||
| `GET /api/v1/dynamics-ax/number-sequences` | Nummerserier med forbrug, format, prognose og flag |
|
||
| `GET /api/v1/dynamics-ax/recids` | RecId pr. tabel med grænse og prognose |
|
||
| `GET /api/v1/dynamics-ax/sequence-samples?instance=&database=&kind=N\|R&key=&days=30` | De daglige målinger bag prognoserne |
|
||
| `GET /api/v1/dynamics-ax/blocking?days=7` | AX-brugere bag blokering |
|
||
|
||
Alle tager `?instance=` for én instans. AX-bruger, vært, program, sætning og agentens login er `[udeladt]`, medmindre `SQLInsight:Web:ApiIncludesSensitiveEvidence` er slået til.
|
||
|
||
## Nyt kundeskema
|
||
|
||
Får vi et rigtigt skema fra en AX 2009- eller 2012-kunde, eksporteres det med
|
||
|
||
```sql
|
||
SELECT s.name AS skema, t.name AS tabel, c.name AS kolonne, TYPE_NAME(c.system_type_id) AS type, c.max_length, c.column_id
|
||
FROM sys.tables t JOIN sys.schemas s ON s.schema_id = t.schema_id JOIN sys.columns c ON c.object_id = t.object_id
|
||
WHERE t.name IN ('SQLDICTIONARY', 'DATAAREA', 'SYSCONFIG', 'BATCH', 'BATCHJOB', 'BATCHJOBHISTORY', 'BATCHGROUP',
|
||
'NUMBERSEQUENCETABLE', 'NUMBERSEQUENCESCOPE', 'NUMBERSEQUENCEREFERENCE', 'SYSTEMSEQUENCES')
|
||
ORDER BY s.name, t.name, c.column_id;
|
||
```
|
||
|
||
og gemmes tabulatorsepareret som `docs/dynamics-ax/schema-ax2009.tsv` eller `schema-ax2012.tsv`. Testene (`AxSchemaAdapterTests`, `DynamicsAxSqlTests`, `SqlScriptTests`) bruger så det rigtige skema i stedet for det dokumenterede, og viser præcis hvilke kolonner versionens adapter ([`AxSchemaAdapter.cs`](../src/SQLInsight.Core/DynamicsAx/AxSchemaAdapter.cs)) forventer, men som mangler. Al viden om en versions tabeller ligger i dens adapter; ret den dér, og opdatér teksterne "ikke verificeret mod kundedata" for versionen (`AxVersions.IsVerified`).
|