How to: Monitoraggio delle API e delle web service di Business Central su ambienti SaaS e Premise
Business Central implementa un nuovo formidabile tool: le telemetrie.
Le telemetrie e il relativo ambiente “Application Insights” sono degli strumenti, utilissimi e semplici, indispensabili per investigare sulle segnalazioni di rallentamenti delle API e delle web service, sono inoltre strumenti ufficiali e non contestabili tramite i quali è possibile replicare a clienti e ad utenti ogni qual volta questi percepiscano problemi di affidabilità sugli ambienti sia SaaS che IaaS/PaaS.
Tramite l’analisi delle telemetrie è infatti possibile tenere sotto controllo tutti gli errori che si verificano durante le chiamate API, con particolare attenzione ai tipici errori che impattano sull’operatività, ovvero gli errori http 429, 5XX e 404.
La configurazione delle Telemetrie su Business Central è oltretutto una operazione semplice ed è possibile farla in pochi minuti.
In questo articolo verranno descritte le operazioni necessaria per ottenere un report che fornisca le informazioni che tipicamente sono utili per investigare sulle segnalazioni degli utenti, ovvero: numero errore http, tempo di esecuzione della chiamata, righe sql coinvolte nell’operazione ed endpoint http che ha causato l’errore.
How to: Creare un report delle informazioni utili sulle segnalazioni degli utenti
Su ambienti SaaS le telemetrie sono sicuramente presenti, su ambienti OnPrem sono supportate, per le API e le web service, solo dalla versione 16 e successive.
Le informazioni di telemetria sono trasferite in tempo reale da Business Central su Azure e sono quindi accessibili e consultabili sul portale stesso, oltre che manipolabili tramite script PowerShell.
Iniziamo quindi con la prima configurazione. La prima operazione consiste nell’aprire la pagina web di “Azure Portal” e creare un nuovo “Application Insights”. L’operazione è molto semplice e si conclude dopo tre click come in figura, la creazione guidata di “Application Insights” richiede l’immissione di poche informazioni e può essere conclusa lasciando le impostazioni di default.
Il risultato finale di questa operazione è una pagina che mostra due dati che ci serviranno successivamente: la “Istrumentation Key” e la “Connection String”.
Questi due dati andranno copiati sulla configurazione delle Telemetrie su Business Central.
Passiamo quindi a Business Central e vediamo come configurare un ambiente SaaS tramite “Admin Center”. Su ambienti SaaS l’admin center è accessibile aprendo la URL: https://businesscentral.dynamics.com/{your_tenant_id}/admin.
Sul blade Environment si procede quindi con la selezione dell’environment sul quale si desidera procedere con l’attivazione delle telemetrie.
Una volta selezionato l’environment, copiare il valore della “Application Insights Key” da “Azure Portal” al relativo campo.
Su ambienti OnPremise di Business Central è necessario invece aprire la schermata della console “Administration Center” e nel tab “Generale” copiare il valore di “Application Insights Instrumentation Key” sulla relativa casella di configurazione.
Terminata la configurazione vediamo ora come accedere ai dati di Telemetria.
Gli strumenti a disposizione sono moltissimi, i principali sono il Portale Azure e PowerShell.
Il blade di “Log Analytics” di Azure consente di interrogare i dati con il nuovo linguaggio KQL.
Per filtrare gli eventi che coinvolgono le chiamate API/ODATA è possibile eseguire una query KQL molto semplice:
traces | where operation_Name == ‘Web Services Call’ and message contains “(Api)”
Questa query darà in uscita un elenco di eventi delle chiamate a WebService eliminando altri tipi di eventi che non sono di interesse.
La finestra che viene mostrata sul blade “Log” di “Application Insights” mostra l’elenco degli eventi e nella parte superiore è possibile digitare ed eseguire la query KQL.
Per ogni riga del singolo evento è possibile espandere e visualizzare i dati dettagliati.
Il risultato HTTP della chiamata è presente all’interno della sottochiave “customDimensions”.
Dato che “customDimensions” è un oggetto di tipo “dynamic type” la query KQL che dobbiamo eseguire per isolare questa informazione è come in figura:
traces
| extend httpStatusCode = parsejson(tostring(parsejson(tostring(customDimensions.httpStatusCode))))
| extend serverExecutionTime = parsejson(tostring(parsejson(tostring(customDimensions.serverExecutionTime))))
| extend serverExecutionTime = parsejson(tostring(parsejson(tostring(customDimensions.serverExecutionTime))))
| extend totalTime = parsejson(tostring(parsejson(tostring(customDimensions.totalTime))))
| extend category = parsejson(tostring(parsejson(tostring(customDimensions.category))))
| extend sqlRowsRead = parsejson(tostring(parsejson(tostring(customDimensions.sqlRowsRead))))
| extend sqlExecutes = parsejson(tostring(parsejson(tostring(customDimensions.sqlExecutes))))
| extend endpoint = parsejson(tostring(parsejson(tostring(customDimensions.endpoint))))
| where operation_Name == 'Web Services Call'
and message contains "(Api)"
| project httpStatusCode, serverExecutionTime , totalTime , category , sqlRowsRead , sqlExecutes , endpoint , operation_Name
Il risultato finale della query è esattamente il report che ci eravamo prefissati di ottenere, ovvero un elenco di chiamate http ad API e Web Service con i principali dati per verificare eventuali malfunzionamenti o rallentamenti.
I dati di Telemetria sono consultabili anche attraverso PowerShell.
Per utilizzare PowerShell è necessario creare una chiave di consultazione sul Portale Azure.
Per fare questo accedere al blade “API Access” e cliccare su “Create API Key”.
La chiave generata deve essere copiata e salvata, non sarà mai più visualizzabile in futuro, quindi, è importante che venga salvata immediatamente in fase di creazione.
Questa chiave e il valore di “Application ID” ci serviranno successivamente in PowerShell.
Prima di procedere con Power Shell è possibile verificare che le API di Application Insights siano accessibili dall’esterno con applicazioni come Insomia o come PostMan.
Ecco un esempio di chiamata:
GET https://api.applicationinsights.io/v1/apps/{app-id}/query?query=
E la query da passare per avere un elenco di eventi:
?query=traces | where timestamp > ago(1d)
Come è possibile notare in figura l’autenticazione con le API di “Application Insights” avviene impostando l’header http “X-Api-Key” con la chiave ottenuta precedentemente sul portale Azure.
Se la verifica delle chiavi ha avuto esito positivo siamo pronti a manipolare i dati tramite script Power Shell.
Il linguaggio Power Shell permette di estrarre i dati e manipolarli come meglio si ritiene opportuno.
Ecco un esempio di script Power Shell che si connette ad Application Insights ed ottiene i dati e visualizza gli stessi:
$key = "{APP_KEY_FROM_AZURE}"
$appId = "{APP_ID_FROM_AZURE}"
$Query=[uri]::EscapeUriString("?query=traces | where timestamp > ago(1d)")
$filename = "{your_path}/{your_file}.kql"
$queryText = Get-Content $filename
$Query=[uri]::EscapeUriString("?query=$queryText")
$headers = @{ "X-Api-Key" = $key; "Content-Type" = "application/json" }
$response = Invoke-WebRequest -uri "https://api.applicationinsights.io/v1/apps/$appId/query$Query" -Headers $headers -Method Get
$json = ConvertFrom-Json $response.Content
$headerRow = $null
$headerRow = $json.tables.columns | Select-Object name
$columnsCount = $headerRow.Count
$logData = @()
foreach ($row in $json.tables.rows) {
$data = new-object PSObject
for ($i = 0; $i -lt $columnsCount; $i++) {
$data | add-member -membertype NoteProperty -name $headerRow[$i].name -value $row[$i]
}
$logData += $data
$data = $null
}
$logData
Lo script esegue un file KQL per filtrare i dati, lo script KQL è esattamente lo stesso che avevamo usato sul portale Azure:
traces
| extend httpStatusCode = parsejson(tostring(parsejson(tostring(customDimensions.httpStatusCode))))
| extend serverExecutionTime = parsejson(tostring(parsejson(tostring(customDimensions.serverExecutionTime))))
| extend serverExecutionTime = parsejson(tostring(parsejson(tostring(customDimensions.serverExecutionTime))))
| extend totalTime = parsejson(tostring(parsejson(tostring(customDimensions.totalTime))))
| extend category = parsejson(tostring(parsejson(tostring(customDimensions.category))))
| extend sqlRowsRead = parsejson(tostring(parsejson(tostring(customDimensions.sqlRowsRead))))
| extend sqlExecutes = parsejson(tostring(parsejson(tostring(customDimensions.sqlExecutes))))
| extend endpoint = parsejson(tostring(parsejson(tostring(customDimensions.endpoint))))
| where operation_Name == 'Web Services Call'
and message contains "(Api)"
| project httpStatusCode, serverExecutionTime , totalTime , category , sqlRowsRead , sqlExecutes , endpoint , operation_Name
| summarize OpNameCount=count() by tostring(httpStatusCode)
Oltre agli strumenti sopra descritti ne esistono molti altri ancora più potenti, uno di questi è “jupyter notebook”.
È possibile scaricare la guida di jupyter notebook
E gli esempi di query KQL
Inoltre, esiste uno strumento di monitoring che permette di mandare alert automaticamente: Azure Monitor.
Ecco alcuni riferimenti su Telemetrie, Application Insights e linguaggio KQL:
https://docs.microsoft.com/en-us/dynamics365/business-central/dev-itpro/administration/telemetry-enable-application-insights
https://dev.applicationinsights.io/documentation/Using-the-API/Query
https://docs.microsoft.com/it-it/azure/data-explorer/kql-quick-reference
Dynamics 365 Developer
Lascia un Commento
Vuoi partecipare alla discussione?Sentitevi liberi di contribuire!