Usare Azure Log Analytics in Generatore API dati

Azure Log Analytics è una piattaforma di registrazione centralizzata che aggrega i log dalle app, dalle risorse di Azure, dalle macchine virtuali, dai contenitori e altro ancora. L'integrazione con Data API Builder (DAB) consente alle aziende di soddisfare i requisiti di conformità, governance e osservabilità. A differenza di Application Insights (incentrato su APM), Log Analytics offre un'aggregazione di log più ampia con il supporto KQL (Kusto Query Language).

Prerequisiti

• File di configurazione DAB esistente.
• Sottoscrizione di Azure con autorizzazioni per creare risorse di Log Analytics.
• Area di lavoro Log Analytics di Azure con:
  • Tabella personalizzata (che termina con _CL)
  • Regola di raccolta dati
  • Un endpoint di raccolta dati (DCE)
• Identità gestita abilitata nell'host DAB (Servizio app di Azure, App per contenitori, macchina virtuale, ecc.).
• CLI generatore di API dati. Installare l'interfaccia della riga di comando

Configurare le risorse di Azure Log Analytics

Prima di configurare DAB, creare le risorse di Azure necessarie.

Creare un'area di lavoro Log Analytics

az monitor log-analytics workspace create \
  --resource-group my-rg \
  --workspace-name my-workspace \
  --location eastus

Creazione di una tabella personalizzata

Le tabelle personalizzate per l'API di inserimento dei log devono terminare con _CL.

1. Nell'area di lavoro Log Analytics passare a Tabelle.
2. Selezionare + Crea>nuovo log personalizzato (basato su DCR).
3. Immettere il nome della tabella , ad esempio DabLogs_CL.
4. Definire lo schema con queste colonne:
   • Time (data e ora)
   • LogLevel (stringa)
   • Message (stringa)
   • Component (stringa)
   • Identifier (stringa)
5. Fare clic su Crea.

Creare un endpoint di raccolta dati (DCE)

az monitor data-collection endpoint create \
  --name my-dce \
  --resource-group my-rg \
  --location eastus \
  --public-network-access Enabled

az monitor data-collection endpoint show \
  --name my-dce \
  --resource-group my-rg \
  --query logsIngestion.endpoint -o tsv

Creare una regola di raccolta dati

1. Passare a Monitor>Regole di Raccolta Dati.
2. Seleziona + Crea.
3. Scegliere sottoscrizione, gruppo di risorse, area.
4. Specificare un nome , ad esempio my-dcr.
5. In Origini dati selezionare Log di testo personalizzati.
6. Configurare:
   • Endpoint raccolta dati: Selezionare il tuo DCE.
   • Destinazione: Area di lavoro Log Analytics.
   • Tabella: tabella personalizzata (DabLogs_CL).
7. Selezionare Rivedi e crea>Crea.
8. Copiare l'ID non modificabile (inizia con dcr-).

Configurare l'autenticazione

DAB usa l'identità gestita di Azure per l'autenticazione in Log Analytics. Nessuna credenziale viene archiviata nella configurazione.

Abilitare l'identità gestita

az webapp identity assign \
  --name my-app \
  --resource-group my-rg

az containerapp identity assign \
  --name my-app \
  --resource-group my-rg \
  --system-assigned

Assegnare autorizzazioni

Concedere il ruolo Monitoring Metrics Publisher alla tua identità gestita sul DCR.

# Get Managed Identity principal ID
PRINCIPAL_ID=$(az webapp identity show \
  --name my-app \
  --resource-group my-rg \
  --query principalId -o tsv)

# Get DCR resource ID
DCR_ID=$(az monitor data-collection rule show \
  --name my-dcr \
  --resource-group my-rg \
  --query id -o tsv)

# Assign role
az role assignment create \
  --assignee $PRINCIPAL_ID \
  --role "Monitoring Metrics Publisher" \
  --scope $DCR_ID

Configurare Log Analytics

Aggiungere una sezione azure-log-analytics sotto runtime.telemetry nel file di configurazione.

{
  "runtime": {
    "telemetry": {
      "azure-log-analytics": {
        "enabled": true,
        "dab-identifier": "my-dab-instance",
        "flush-interval-seconds": 10,
        "auth": {
          "custom-table-name": "DabLogs_CL",
          "dcr-immutable-id": "dcr-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
          "dce-endpoint": "https://my-dce.eastus-1.ingest.monitor.azure.com"
        }
      }
    }
  }
}

Proprietà di configurazione

Command-line

Configurare Log Analytics tramite dab configure.

Abilitare Log Analytics

dab configure \
  --runtime.telemetry.azure-log-analytics.enabled true

dab configure ^
  --runtime.telemetry.azure-log-analytics.enabled true

Impostare l'identificatore DAB

dab configure \
  --runtime.telemetry.azure-log-analytics.dab-identifier my-dab-instance

dab configure ^
  --runtime.telemetry.azure-log-analytics.dab-identifier my-dab-instance

Impostare l'intervallo di scaricamento

dab configure \
  --runtime.telemetry.azure-log-analytics.flush-interval-seconds 10

dab configure ^
  --runtime.telemetry.azure-log-analytics.flush-interval-seconds 10

Impostare il nome della tabella personalizzata

dab configure \
  --runtime.telemetry.azure-log-analytics.auth.custom-table-name DabLogs_CL

dab configure ^
  --runtime.telemetry.azure-log-analytics.auth.custom-table-name DabLogs_CL

Impostare l'ID non modificabile di DCR

dab configure \
  --runtime.telemetry.azure-log-analytics.auth.dcr-immutable-id dcr-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

dab configure ^
  --runtime.telemetry.azure-log-analytics.auth.dcr-immutable-id dcr-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Impostare l'endpoint DCE

dab configure \
  --runtime.telemetry.azure-log-analytics.auth.dce-endpoint https://my-dce.eastus-1.ingest.monitor.azure.com

dab configure ^
  --runtime.telemetry.azure-log-analytics.auth.dce-endpoint https://my-dce.eastus-1.ingest.monitor.azure.com

Avvia DAB

Avviare DAB con il file di configurazione:

dab start

Controllare i log di avvio di DAB per:

Azure Log Analytics is enabled.

Come funziona

Quando Log Analytics è abilitato, DAB:

1. Esegue l'autenticazione in Azure usando l'identità gestita dell'host.
2. Raggruppa le voci di log in base a flush-interval-seconds.
3. Invia i log all'endpoint di raccolta dati (DCE).
4. DCE instrada i log tramite la regola di raccolta dati (DCR) per la trasformazione.
5. DCR inserisce i log nella tabella di Log Analytics personalizzata.

Flusso di dati

DAB Application
    ↓
ILogger (ASP.NET Core)
    ↓
Log Analytics Logger Provider
    ↓
Managed Identity Authentication
    ↓
Data Collection Endpoint (DCE)
    ↓
Data Collection Rule (DCR)
    ↓
Log Analytics Workspace (Custom Table)

Cosa viene acquisito

Struttura di log

Ogni voce di log inviata a Log Analytics contiene questi campi:

Eseguire query sui log in Log Analytics

1. Aprire l'area di lavoro Log Analytics nel portale di Azure.

2. Passare a Log ed eseguire una query KQL:

   DabLogs_CL
   | where Identifier_s == "my-dab-instance"
   | where LogLevel_s in ("Warning", "Error")
   | where TimeGenerated > ago(1h)
   | project TimeGenerated, LogLevel_s, Message_s, Component_s
   | order by TimeGenerated desc
   

Interrogazioni di esempio

Conteggio dei log per livello:

DabLogs_CL
| where TimeGenerated > ago(24h)
| summarize Count=count() by LogLevel_s

Trovare errori in un componente specifico:

DabLogs_CL
| where Component_s contains "SqlQueryExecutor"
| where LogLevel_s == "Error"
| project TimeGenerated, Message_s

Considerazioni sulle prestazioni e i costi

Comportamento di invio in batch

DaB batch registra i log e li invia ogni flush-interval-seconds:

• 5 secondi (impostazione predefinita): bilanciamento ottimale per la maggior parte degli scenari.
• 1-2 secondi: registrazione quasi in tempo reale (chiamate API più elevate, costi più elevati).
• 10-60 secondi: chiamate API ridotte ma log ritardati.

Ottimizzazione dei costi

I prezzi di Log Analytics si basano su:

1. Inserimento dati: per GB inseriti.
2. Conservazione dei dati: per GB al mese dopo il livello gratuito.

Ridurre i costi:

• Aumentare flush-interval-seconds per raggruppare più log.
• Usare filtri a livello di log per escludere i log dettagliati. Per altre informazioni, vedere Personalizzare il livello di dettaglio del log.
• Impostare la conservazione dei dati appropriata nell'area di lavoro Log Analytics.

Esempio: filtrare per ridurre il volume

{
  "runtime": {
    "telemetry": {
      "log-level": {
        "Default": "Warning",
        "Microsoft": "Error"
      },
      "azure-log-analytics": {
        "enabled": true,
        "flush-interval-seconds": 30,
        "auth": {
          "custom-table-name": "DabLogs_CL",
          "dcr-immutable-id": "dcr-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
          "dce-endpoint": "https://my-dce.eastus-1.ingest.monitor.azure.com"
        }
      }
    }
  }
}

In questo modo vengono inviati solo i log degli avvisi e degli errori , riducendo significativamente il volume.

Conservazione dei dati

La conservazione dei dati di Log Analytics è configurabile per ogni area di lavoro:

Configurare la conservazione: l'area di lavoro Log Analytics → Utilizzo e i costi stimati → conservazione dei dati.

Risoluzione dei problemi

Log non visualizzati in Log Analytics

Sintomo: DAB viene avviato correttamente, ma non vengono visualizzati log nell'area di lavoro Log Analytics.

Possibili cause:

• Configurazione incompleta: controllare i log di avvio di DAB per individuare errori come Logs won't be sent to Azure Log Analytics because the Custom Table Name is not available in the config file. Verificare tutte le proprietà di autenticazione necessarie: custom-table-name, dcr-immutable-id, dce-endpoint.

• Identità gestita non assegnata: verificare che l'identità gestita sia abilitata con az webapp identity show --name my-app --resource-group my-rg. Controllare l'assegnazione di ruolo con az role assignment list --assignee <principal-id> --scope <dcr-id>.

• Endpoint DCE o ID DCR non corretto: verificare che il formato dell'endpoint DCE sia https://<dce-name>.<region>-1.ingest.monitor.azure.com. Verificare che l'ID non modificabile di DCR inizi con dcr-.

• Tabella personalizzata non esistente: le tabelle personalizzate devono terminare con _CL. Lo schema della tabella deve corrispondere alla struttura del log.

Errore: L'intervallo di svuotamento deve essere positivo

Causa: flush-interval-seconds è impostato su 0 o un valore negativo.

Soluzione: impostare su flush-interval-seconds un numero intero positivo (minimo 1).

I log DAB mostrano "Azure Log Analytics è disabilitato"

Causa: enabled è o manca false dalla configurazione.

Soluzione: impostare enabled: true nella configurazione.

Log Analytics contro Application Insights

Usare Application Insights quando sono necessarie funzionalità di APM come il rilevamento delle richieste, il mapping delle dipendenze e la profilatura delle prestazioni. Usare Log Analytics quando è necessaria la registrazione centralizzata tra più risorse con requisiti di conformità aziendali.

Contenuti correlati

• Usare Application Insights
• Usare OpenTelemetry
• Personalizzare il livello di dettaglio del log
• Panoramica delle regole di raccolta dati
• identità gestite per le risorse di Azure