Come integrare Gestione API di Azure con Azure Application Insights
SI APPLICA A: Tutti i livelli di Gestione API
È possibile integrare facilmente Application Insights di Azure con Gestione API di Azure. Azure Application Insights è un servizio estendibile per sviluppatori Web che compilano e gestiscono app in più piattaforme. Questa guida illustra le procedure per:
- Analizzare l'integrazione di Application Insights in Gestione API.
- Individuare le strategie per ridurre l'impatto sulle prestazioni nell'istanza del servizio Gestione API.
Nota
In un'area di lavoro Gestione API un proprietario dell'area di lavoro può integrare in modo indipendente Application Insights e abilitare la registrazione di Application Insights per le API dell'area di lavoro. Le linee guida generali per l'integrazione di un'area di lavoro con Application Insights sono simili alle linee guida per un'istanza di Gestione API, ma la configurazione ha come ambito solo l'area di lavoro. Attualmente, è necessario integrare Application Insights in un'area di lavoro configurando una chiave di strumentazione o stringa di connessione.
Prerequisiti
È necessaria un'istanza di Gestione API di Azure. Innanzitutto, creare un'istanza.
Per usare Application Insights, creare un'istanza del servizio Application Insights. Per creare un'istanza usando il portale di Azure, vedere Risorse di Application Insights basate sull'area di lavoro.
Nota
La risorsa Application Insights può essere in una sottoscrizione diversa o anche in un tenant diverso rispetto alla risorsa Gestione API.
Se si prevede di configurare un'identità gestita per Gestione API da usare con Application Insights, è necessario completare i passaggi seguenti:
Abilitare un'identità gestita per Gestione API assegnata dal sistema o assegnata dall'utente nell'istanza di Gestione API.
- Se si abilita un'identità gestita assegnata dall'utente, prendere nota dell'ID client dell'identità.
Assegnare all'identità il ruolo server di pubblicazione delle metriche di monitoraggio, con ambito della risorsa di Application Insights. Per assegnare il ruolo, usare il portale di Azure o altri strumenti di Azure.
Panoramica dello scenario
Di seguito sono riportati i passaggi di livello elevato per questo scenario.
Innanzitutto, creare una connessione tra Application Insights e Gestione API
È possibile creare una connessione tra Application Insights e Gestione API usando il portale di Azure, l'API REST o gli strumenti di Azure correlati. Gestione API configura una risorsa logger per la connessione.
Nota
Se la risorsa di Application Insights si trova in un tenant diverso, è necessario creare il logger usando l'API REST, come illustrato in una sezione successiva di questo articolo.
Importante
Attualmente, nel portale, Gestione API supporta solo le connessioni ad Application Insights usando una chiave di strumentazione di Application Insights. Per usare una stringa di connessione di Application Insights o un'identità gestita di Gestione API, usare il modello API REST, Bicep o ARM per creare il logger. Altre informazioni sulle stringhe di connessione di Application Insights.
Secondo, abilitare la registrazione di Application Insights per l'API o le API.
In questo articolo viene abilitata la registrazione di Application Insights per l'API usando il portale di Azure. Gestione API configura una risorsa diagnostica per l'API.
Creare una connessione usando il portale di Azure
Seguire questa procedura per usare il portale di Azure per creare una connessione tra Application Insights e Gestione API.
Passare all'istanza del servizio Gestione API di Azure nel portale di Azure.
Selezionare Application Insights nel menu a sinistra.
Seleziona + Aggiungi.
Selezionare l'istanza di Application Insights creata in precedenza e immettere una breve descrizione.
Per abilitare monitoraggio della disponibilità dell'istanza di Gestione API in Application Insights, selezionare la casella di controllo Aggiungi monitoraggio disponibilità.
- Questa impostazione convalida regolarmente se l'endpoint del gateway di Gestione API risponde.
- I risultati vengono visualizzati nel riquadro Disponibilità dell'istanza di Application Insights.
Seleziona Crea.
Verificare che il nuovo logger di Application Insights sia ora visualizzato nell'elenco.
Nota
A parte, viene creata un'entità logger nell'istanza di Gestione API, contenente la chiave di strumentazione dell'istanza di Application Insights.
Suggerimento
Se è necessario aggiornare la chiave di strumentazione configurata nel logger di Application Insights, selezionare la riga del logger nell'elenco (non il nome del logger). Immettere la chiave di strumentazione e selezionare Salva.
Creare una connessione usando l'API REST, Bicep o il modello di Resource Manager
Seguire questa procedura per usare l'API REST, Bicep o il modello di Resource Manager per creare una connessione tra Application Insights e Gestione API. È possibile configurare un logger che usa una stringa di connessione, un'identità gestita assegnata dal sistema o un'identità gestita assegnata dall'utente.
Logger con credenziali della stringa di connessione
La stringa di connessione di Application Insights viene visualizzata nella sezione Panoramica della risorsa di Application Insights.
Usare il Gestione API Logger - Creare o aggiornare l'API REST con il corpo della richiesta seguente.
Se si configura il logger per un'area di lavoro, usare logger dell'area di lavoro - Creare o aggiornare l'API REST.
{
"properties": {
"loggerType": "applicationInsights",
"description": "adding a new logger with connection string",
"credentials": {
"connectionString":"InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;..."
}
}
}
Logger con credenziali di identità gestita assegnata dal sistema
Vedere i prerequisiti per l'utilizzo dell'identità gestita di Gestione API.
Usare il Gestione API Logger - Creare o aggiornare l'API REST con il corpo della richiesta seguente.
{
"properties": {
"loggerType": "applicationInsights",
"description": "adding a new logger with system-assigned managed identity",
"credentials": {
"connectionString":"InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...",
"identityClientId":"SystemAssigned"
}
}
}
Logger con credenziali di identità gestita assegnata dall'utente
Vedere i prerequisiti per l'utilizzo dell'identità gestita di Gestione API.
Usare il Gestione API Logger - Creare o aggiornare l'API REST con il corpo della richiesta seguente.
{
"properties": {
"loggerType": "applicationInsights",
"description": "adding a new logger with user-assigned managed identity",
"credentials": {
"connectionString":"InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...",
"identityClientId":"<ClientID>"
}
}
}
Abilitare la registrazione di Application Insights per l'API
Utilizzare la seguente procedura per abilitare la registrazione di Application Insights per un'API. È possibile anche abilitare la registrazione di Application Insights per tutte le API.
Passare all'istanza del servizio Gestione API di Azure nel portale di Azure.
Selezionare API nel menu a sinistra.
Fare clic sull'API, in questo caso Demo Conference API. Se configurata, selezionare una versione.
Suggerimento
Per abilitare la registrazione per tutte le API, selezionare Tutte le API.
Passare alla scheda Impostazioni dalla barra in alto.
Scorrere verso il basso fino alla sezione Log di diagnostica.
Selezionare la casella Abilita.
Selezionare il logger associato nell'elenco a discesa Destinazione.
Immettere 100 come Campionamento (%) e selezionare la casella di controllo Registra sempre gli errori.
Lasciare le altre impostazioni invariate. Per informazioni dettagliate sulle impostazioni, vedere Informazioni di riferimento sulle impostazioni dei log di diagnostica.
Avviso
Sovrascrivere il valore predefinito 0 in Numero di byte di payload da registrare potrebbe ridurre in modo significativo le prestazioni delle API.
Seleziona Salva.
A parte viene creata un'entità Diagnostica denominata
applicationinsights
a livello di API.
Nota
Le richieste hanno esito positivo dopo che Gestione API invia l'intera risposta al client.
Logger per una singola API o per tutte le API
È possibile specificare logger in livelli diversi:
- Un logger per una singola API
- Un logger per tutte le API
Specificando entrambi:
- Per impostazione predefinita, il logger per una singola API (livello più granulare) sostituisce quello per tutte le API.
- Se i logger configurati a due livelli sono diversi ed è necessario che entrambi i logger ricevano i dati di telemetria (multiplexing), contattare il supporto tecnico Microsoft. Il multiplexing non è supportato se si usa lo stesso logger (destinazione Application Insights) a livello di "Tutte le API" e a livello di singola API. Per il corretto funzionamento del multiplexing, è necessario configurare diversi logger a livello di "Tutte le API" e a livello di singola API e richiedere assistenza dal supporto tecnico Microsoft per abilitare il multiplexing per il servizio.
Quali dati vengono aggiunti ad Application Insights
Application Insights riceve:
Elemento telemetria | Descrizione |
---|---|
Richiedi | Per tutte le richieste in ingresso:
|
Dipendenza | Per ogni richiesta inoltrata a un servizio back-end:
|
Eccezione | Per tutte le richieste non riuscite:
|
Traccia | Se si configura un criterio di traccia. L'impostazione severity nel criterio trace deve essere uguale o maggiore dell'impostazione verbosity nella registrazione di Application Insights. |
Nota
Vedere Limiti di Application Insights per informazioni sulle dimensioni massime e sul numero di metriche ed eventi per ogni istanza di Application Insights.
Emettere metriche personalizzate
È possibile emettere metriche personalizzate in Application Insights dall'istanza di Gestione API. Gestione API emette metriche personalizzate usando i criteri emit-metric.
Nota
Le metriche personalizzate sono una funzionalità di anteprima di Monitoraggio di Azure e sono soggette a limitazioni.
Per abilitare le metriche personalizzate, seguire questa procedura di configurazione.
Abilitare Metriche personalizzate (anteprima) con dimensioni personalizzate nell'istanza di Application Insights.
- Passare all'istanza di Application Insights nel portale.
- Nel menu a sinistra, selezionare Utilizzo e costi stimati.
- Selezionare Metriche personalizzate (anteprima)>Con dimensioni.
- Seleziona OK.
Aggiungere la proprietà
"metrics": true
all'entità diagnosticaapplicationInsights
configurata in Gestione API. Attualmente è necessario aggiungere questa proprietà usando l'API REST Diagnostica - Creare o aggiornare di Gestione API. Ad esempio:PUT https://management.azure.com/subscriptions/{SubscriptionId}/resourceGroups/{ResourceGroupName}/providers/Microsoft.ApiManagement/service/{APIManagementServiceName}/diagnostics/applicationinsights { [...] { "properties": { "loggerId": "/subscriptions/{SubscriptionId}/resourceGroups/{ResourceGroupName}/providers/Microsoft.ApiManagement/service/{APIManagementServiceName}/loggers/{ApplicationInsightsLoggerName}", "metrics": true [...] } }
Assicurarsi che il logger di Application Insights sia configurato per l'ambito per cui si intende emettere metriche personalizzate (tutte le API o una singola API). Per altre informazioni, vedere la sezione Abilitare la registrazione di Application Insights per l'API, illustrata in precedenza in questo articolo.
Configurare il criterio
emit-metric
in un ambito in cui è configurata la registrazione di Application Insights (tutte le API o una singola API) ed è abilitata per le metriche personalizzate. Per i dettagli sul criterio, vedere le informazioni di riferimento sul criterioemit-metric
.
Limiti per le metriche personalizzate
Monitoraggio di Azure impone limiti di utilizzo per le metriche personalizzate che possono influire sulla capacità di emettere metriche da Gestione API. Ad esempio, Monitoraggio di Azure imposta attualmente un limite di 10 chiavi di dimensione per metrica e un limite di 50.000 serie temporali attive totali per area in una sottoscrizione (in un periodo di 12 ore).
Questi limiti hanno le implicazioni seguenti per la configurazione di metriche personalizzate in Gestione API:
È possibile configurare un massimo di 10 dimensioni personalizzate per criterio
emit-metric
.Il numero di serie temporali attive generate dal criterio
emit-metric
entro un periodo di 12 ore è il prodotto del numero di valori univoci di ogni dimensione configurata durante quel periodo. Ad esempio, se nel criterio sono state configurate tre dimensioni personalizzate e ogni dimensione ha 10 valori possibili all'interno del periodo, il criterioemit-metric
contribuirà con 1.000 (10 x 10 x 10) serie temporali attive.Se si configura il criterio
emit-metric
in più istanze di Gestione API che si trovano nella stessa area di una sottoscrizione, tutte le istanze possono contribuire al limite di serie temporali attive a livello di area.
Implicazioni sulle prestazioni e campionamento dei log
Avviso
La registrazione di tutti gli eventi può comportare gravi implicazioni per le prestazioni, a seconda della frequenza delle richieste in ingresso.
In base ai test di carico interni, l'abilitazione della funzionalità di registrazione ha causato una riduzione del 40%-50% della velocità effettiva quando la frequenza delle richieste superava le 1.000 richieste al secondo. Application Insights è progettato per valutare le prestazioni delle applicazioni usando l'analisi statistica. Non è:
- Pensato per essere un sistema di controllo.
- Adatto per la registrazione di ogni singola richiesta per le API con volume elevato.
È possibile modificare il numero di richieste registrate regolando l'impostazione Campionamento. Un valore pari al 100% indica che vengono registrate tutte le richieste, mentre un valore pari allo 0% indica che non vengono eseguite registrazioni.
Il campionamento consente di ridurre il volume dei dati di telemetria, impedendo efficacemente un considerevole degrado delle prestazioni, pur conservando i vantaggi della registrazione.
Per migliorare i problemi di prestazioni, ignorare:
- Intestazioni di richiesta e risposta.
- Registrazione del corpo.
Video
Risoluzione dei problemi
Risoluzione del problema del flusso di dati di telemetria da Gestione API ad Application Insights:
- Verificare se esiste una risorsa AMPLS (Azure Monitor Private Link Scope) collegata all'interno della rete virtuale in cui è connessa la risorsa Gestione API. Le risorse AMPLS hanno un ambito globale tra le sottoscrizioni e sono responsabili della gestione delle query e dell'inserimento dei dati per tutte le risorse di Monitoraggio di Azure. È possibile che AMPLS sia stato configurato con una modalità di accesso solo privato specificamente per l'inserimento dati. In questi casi, includere la risorsa di Application Insights e la risorsa di Log Analytics associata in AMPLS. Dopo aver apportato questa aggiunta, i dati di Gestione API verranno inseriti correttamente nella risorsa di Application Insights, risolvendo il problema di trasmissione dei dati di telemetria.
Contenuto correlato
- Altre informazioni su Azure Application Insights.
- Considerare la possibilità di eseguire la registrazione con Hub eventi di Azure.
- Informazioni sulla visualizzazione dei dati da Application Insights con Grafana con gestione Azure