Condividi tramite

Come integrare Gestione API di Azure con Azure Application Insights

  • Articolo

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 di 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 indicazioni generali per integrare un'area di lavoro con Application Insights sono simili alle indicazioni per un'istanza di Gestione API; tuttavia, la configurazione ha come ambito solo l'area di lavoro. È attualmente necessario integrare Application Insights in un'area di lavoro configurando una stringa di connessione (scelta consigliata) o una chiave di strumentazione.

Avviso

Quando si usa un gateway self-hosted, non si garantisce che venga eseguito il push di tutti i dati di telemetria in Azure Application Insights, in quanto si basa sul buffer in memoria di Application Insights.

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 le credenziali dell'identità gestita da usare con Application Insights, completare la procedura seguente:

    1. Abilitare un'identità gestita per Gestione API assegnata dal sistema o assegnata dall'utente.

      • Se si abilita un'identità gestita assegnata dall'utente, prendere nota dell'ID client dell'identità.

    2. 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.

  1. Creare innanzitutto 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.

    Importante

    Attualmente, nel portale, Gestione API supporta solo le connessioni ad Application Insights usando una chiave di strumentazione di Application Insights. Per una maggiore sicurezza, è consigliabile usare una stringa di connessione di Application Insights con un'identità gestita di Gestione API. Per configurare la stringa di connessione con le credenziali dell'identità gestita, usare l'API REST o gli strumenti correlati, come illustrato in una sezione successiva di questo articolo. Altre informazioni sulle stringhe di connessione di Application Insights.

    Nota

    Se la risorsa di Application Insights si trova in un tenant diverso, è necessario creare il logger usando l'API REST o gli strumenti correlati, come illustrato in una sezione successiva di questo articolo.

  2. Abilitare quindi 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.

Nota

Quando possibile, Microsoft consiglia di usare una stringa di connessione con credenziali dell'identità gestita per una sicurezza avanzata. Per configurare queste credenziali, usare l'API REST o gli strumenti correlati, come illustrato in una sezione successiva di questo articolo.

  1. Passare all'istanza del servizio Gestione API di Azure nel portale di Azure.

  2. Selezionare Application Insights nel menu a sinistra.

  3. Seleziona + Aggiungi.
    Screenshot che mostra dove aggiungere una nuova connessione

  4. Selezionare l'istanza di Application Insights creata in precedenza e immettere una breve descrizione.

  5. 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.

  6. Seleziona Crea.

  7. Verificare che il nuovo logger di Application Insights sia ora visualizzato nell'elenco.

    Screenshot che mostra dove visualizzare il logger di Application Insights appena creato.

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 un logger di Application Insights per l'istanza di Gestione API. È possibile configurare un logger che usa la stringa di connessione con credenziali dell'identità gestita (scelta consigliata) o un logger che usa solo una stringa di connessione.

Vedere i prerequisiti per l'utilizzo dell'identità gestita di Gestione API.

La stringa di connessione di Application Insights viene visualizzata nella sezione Panoramica della risorsa di Application Insights.

Stringa di connessione con identità gestita assegnata dal sistema

Usare l'API REST Gestione API Logger - Creare o aggiornare con il corpo della richiesta seguente.

{
  "properties": {
    "loggerType": "applicationInsights",
    "description": "Application Insights logger with system-assigned managed identity",
    "credentials": {
         "connectionString":"InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...",
         "identityClientId":"SystemAssigned"
    }
  }
}

Stringa di connessione con identità gestita assegnata dall'utente

Usare l'API REST Gestione API Logger - Creare o aggiornare con il corpo della richiesta seguente.

{
  "properties": {
    "loggerType": "applicationInsights",
    "description": "Application Insights logger with user-assigned managed identity",
    "credentials": {
         "connectionString":"InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;...",
         "identityClientId":"<ClientID>"
    }
  }
}

Logger solo con credenziali della stringa di connessione

La stringa di connessione di Application Insights viene visualizzata nella sezione Panoramica della risorsa di Application Insights.

Usare l'API REST Gestione API Logger - Creare o aggiornare con il corpo della richiesta seguente.

Se si sta configurando il logger per un'area di lavoro, usare l'API REST Logger area di lavoro - Creare o aggiornare.

{
  "properties": {
    "loggerType": "applicationInsights",
    "description": "Application Insights logger with connection string",
    "credentials": {
         "connectionString":"InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://xxxx.applicationinsights.azure.com/;..."    
    }
  }
}

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.

  1. Passare all'istanza del servizio Gestione API di Azure nel portale di Azure.

  2. Selezionare API nel menu a sinistra.

  3. 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.

  4. Passare alla scheda Impostazioni dalla barra in alto.

  5. Scorrere verso il basso fino alla sezione Log di diagnostica.
    Logger di Application Insights

  6. Selezionare la casella Abilita.

  7. Selezionare il logger associato nell'elenco a discesa Destinazione.

  8. Immettere 100 come Campionamento (%) e selezionare la casella di controllo Registra sempre gli errori.

  9. 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.

  10. Seleziona Salva.

  11. 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:
  • richiesta front-end
  • risposta front-end
Dipendenza Per ogni richiesta inoltrata a un servizio back-end:
  • richiesta back-end
  • risposta back-end
Eccezione Per tutte le richieste non riuscite:
  • Non è riuscita a causa di una connessione client chiusa
  • Ha attivato una sezione on-error dei criteri delle API
  • Ha un codice di stato HTTP della risposta corrispondente a 4xx o 5xx
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 genera metriche personalizzate usando criteri quali emit-metric e azure-openai-emit-token-metric. La sezione seguente usa il criterio emit-metric come esempio.

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.

  1. Abilitare Metriche personalizzate (anteprima) con dimensioni personalizzate nell'istanza di Application Insights.

    1. Passare all'istanza di Application Insights nel portale.
    2. Nel menu a sinistra, selezionare Utilizzo e costi stimati.
    3. Selezionare Metriche personalizzate (anteprima)>Con dimensioni.
    4. Seleziona OK.

  2. Aggiungere la proprietà "metrics": true all'entità diagnostica applicationInsights 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
        [...]
    }
}

  3. 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.

  4. 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 criterio emit-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 un criterio di Gestione API, emit-metric ad esempio o azure-openai-emit-token-metric:

  • È possibile configurare un massimo di 10 dimensioni personalizzate per criterio .

  • Il numero di serie temporali attive generate dal criterio 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 criterio contribuirà con 1.000 (10 x 10 x 10) serie temporali attive.

  • Se si configura il criterio 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.

Altre informazioni sulle limitazioni e sulle considerazioni sulla progettazione per le metriche personalizzate in Monitoraggio di Azure.

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