Usare Azure Application Insights in Data API Builder

Azure Application Insights è un servizio application performance monitoring (APM) che acquisisce automaticamente richieste, tracce, eccezioni e metriche delle prestazioni. L'integrazione con Data API Builder (DAB) consente di monitorare il comportamento di runtime, diagnosticare i problemi e ottimizzare le prestazioni nell'ambiente di produzione.

Prerequisiti

• File di configurazione DAB esistente.
• Risorsa di Azure Application Insights.
• Stringa di connessione di Application Insights.
• CLI generatore di API dati. Installare l'interfaccia della riga di comando

Ottenere la stringa di connessione

Prima di configurare DAB, ottenere la stringa di connessione di Application Insights da Azure.

Portale di Azure

1. Passare alla risorsa di Application Insights nel portale di Azure.
2. Passare a Panoramica o Proprietà.
3. Copiare la stringa di connessione (non la chiave di strumentazione).

Azure CLI

az monitor app-insights component show \
  --app my-app-insights \
  --resource-group my-rg \
  --query connectionString -o tsv

az monitor app-insights component show ^
  --app my-app-insights ^
  --resource-group my-rg ^
  --query connectionString -o tsv

Formato della stringa di connessione

InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://<region>.in.applicationinsights.azure.com/;LiveEndpoint=https://<region>.livediagnostics.monitor.azure.com/

Configurare Application Insights

Aggiungere una sezione application-insights sotto runtime.telemetry nel file di configurazione.

{
  "runtime": {
    "telemetry": {
      "application-insights": {
        "enabled": true,
        "connection-string": "@env('app-insights-connection-string')"
      }
    }
  }
}

Questa configurazione usa una variabile di ambiente per la stringa di connessione. Definirlo in un .env file:

app-insights-connection-string="InstrumentationKey=...;IngestionEndpoint=...;LiveEndpoint=..."

Command-line

Configurare Application Insights tramite dab add-telemetry.

Abilita gli Approfondimenti sull'Applicazione

dab add-telemetry \
  --app-insights-enabled true \
  --app-insights-conn-string "@env('app-insights-connection-string')"

dab add-telemetry ^
  --app-insights-enabled true ^
  --app-insights-conn-string "@env('app-insights-connection-string')"

Disabilitare Application Insights

dab add-telemetry \
  --app-insights-enabled false

dab add-telemetry ^
  --app-insights-enabled false

Avvia DAB

Avviare DAB con il file di configurazione:

dab start

Controllare i log di avvio per la conferma:

Application Insights telemetry is enabled with connection string from config.

Come funziona

Quando Application Insights è abilitato, DAB:

1. Registra Application Insights SDK usando AddApplicationInsightsTelemetry().
2. Registra un inizializzatore di telemetria personalizzato per arricchire tutti i dati di telemetria con proprietà specifiche di DAB.
3. Configura TelemetryClient con la stringa di connessione dal file di configurazione.
4. Si integra con il logging di ASP.NET Core per catturare i log della console come tracce.

Flusso di dati

DAB Application
    ↓
ILogger (ASP.NET Core)
    ↓
ApplicationInsightsLoggerProvider
    ↓
AppInsightsTelemetryInitializer (adds custom properties)
    ↓
TelemetryClient
    ↓
Application Insights (Azure)

Cosa viene acquisito

Arricchimento dei dati di telemetria

DAB arricchisce automaticamente tutti i dati di telemetria di Application Insights con proprietà personalizzate:

Queste proprietà consentono di filtrare e correlare i dati di telemetria specifici di DAB in Application Insights.

Eseguire query sui dati di telemetria in Azure

Tracce (log)

traces
| where customDimensions["ProductName"] startswith "dab-"
| order by timestamp desc
| project timestamp, message, severityLevel

Mapping livello di log:

Requests

requests
| where customDimensions["ProductName"] startswith "dab-"
| order by timestamp desc
| project timestamp, name, duration, resultCode, success

Exceptions

exceptions
| where customDimensions["ProductName"] startswith "dab-"
| order by timestamp desc
| project timestamp, type, outerMessage, details

Filtrare in base alla versione DAB

traces
| where customDimensions["Component.Version"] == "1.2.3"
| project timestamp, message, severityLevel

Trovare query GraphQL lente

requests
| where name contains "/graphql"
| where duration > 1000
| project timestamp, name, duration, resultCode
| order by duration desc

Frequenza di esito positivo della richiesta

requests
| where customDimensions["ProductName"] startswith "dab-"
| summarize 
    Total = count(),
    Success = countif(success == true),
    Failed = countif(success == false)
| extend SuccessRate = (Success * 100.0) / Total

Principali operazioni lente del database

dependencies
| where type == "SQL" or type == "Azure Cosmos DB"
| top 10 by duration desc
| project timestamp, name, duration, target, data

Metriche in tempo reale

Live Metrics fornisce il monitoraggio in tempo reale con <una latenza di 1 secondo. Viene abilitato automaticamente quando Application Insights è configurato.

Accedere alle metriche in tempo reale

1. Aprire la risorsa di Application Insights nel portale di Azure.
2. Passare a Metriche attive nel menu a sinistra.
3. Avviare l'applicazione DAB.
4. Entro pochi secondi, i dati in tempo reale verranno visualizzati.

Cosa vedi

Campionamento e conservazione dei dati

Campionamento adattivo

Application Insights SDK campiona automaticamente i dati di telemetria quando il volume è elevato per ridurre i costi e rimanere entro i limiti di velocità. La frequenza di campionamento viene visualizzata nell'interfaccia utente di Application Insights.

Comportamento predefinito:

• Traffico basso: tutti i dati di telemetria inviati (100%)
• Traffico elevato: il campionamento riduce automaticamente il volume
• Dati rappresentativi mantenuti

Conservazione dei dati

Configurare la conservazione: Application Insights → Utilizzo e costi stimati → conservazione dei dati.

Considerazioni sulle prestazioni

Sovraccarico dei dati di telemetria

Application Insights aggiunge un sovraccarico minimo:

• Memoria: ~10-50 MB a seconda del traffico
• CPU: <1% con carico normale
• Latenza: <1 ms per richiesta (asincrona)

Procedure consigliate

• Usare le variabili di ambiente per le stringhe di connessione.
• Disabilitare in fase di sviluppo locale, se non necessario.
• Monitorare la frequenza di campionamento nell'ambiente di produzione.
• Impostare la conservazione dei dati appropriata per gestire i costi.

Disabilitare in fase di sviluppo

{
  "runtime": {
    "telemetry": {
      "application-insights": {
        "enabled": false
      }
    }
  }
}

Esportare e visualizzare

I dati di telemetria vengono esportati tramite Application Insights SDK. L'SDK raggruppa i dati in batch e li invia periodicamente.

Stringa di connessione vs. chiave di strumentazione

Usare stringhe di connessione (scelta consigliata)

{
  "connection-string": "InstrumentationKey=...;IngestionEndpoint=https://eastus.in.applicationinsights.azure.com/"
}

Vantaggi:

• Endpoint specifici dell'area (latenza inferiore)
• Supporta servizi di cloud di sovranità
• A prova di futuro (approccio consigliato da Microsoft)

Chiave di strumentazione legacy

Anche se ancora supportato, Microsoft consiglia le stringhe di connessione per le nuove implementazioni.

{
  "connection-string": "InstrumentationKey=00000000-0000-0000-0000-000000000000"
}

Risoluzione dei problemi

Errore: "La stringa di connessione di Application Insights non può essere null o vuota se abilitata"

Causa: enabled è impostato su true ma connection-string è mancante o vuoto.

Soluzione: specificare una stringa di connessione valida quando si abilita Application Insights oppure impostare enabled su false.

{
  "runtime": {
    "telemetry": {
      "application-insights": {
        "enabled": true,
        "connection-string": "@env('app-insights-connection-string')"
      }
    }
  }
}

DAB viene avviato ma non viene visualizzata alcuna telemetria

Controllare i log di avvio per questi messaggi:

dab start --LogLevel Information

dab start --LogLevel Information

Messaggio di operazione riuscita:

Application Insights telemetry is enabled with connection string from config.

Messaggi di avviso:

Logs won't be sent to Application Insights because an Application Insights connection string is not available in the runtime config.

Application Insights are disabled.

Messaggio di errore:

Telemetry client is not initialized.

Verificare la variabile di ambiente

echo $app-insights-connection-string

echo %app-insights-connection-string%

Eseguire il test con la stringa di connessione diretta

Usare temporaneamente una stringa di connessione diretta (non una variabile di ambiente) per verificare che la stringa sia valida:

{
  "connection-string": "InstrumentationKey=...;IngestionEndpoint=..."
}

Se funziona, il problema riguarda il caricamento di variabili di ambiente.

Contenuti correlati

• Usare Azure Log Analytics
• Usare OpenTelemetry
• Personalizzare il livello di dettaglio del log
• Panoramica di Application Insights
• Application Insights per ASP.NET Core