Verwenden von Azure Log Analytics im Daten-API-Generator

Azure Log Analytics ist eine zentrale Protokollierungsplattform, die Protokolle aus Apps, Azure-Ressourcen, VMs, Containern und mehr aggregiert. Die Integration in den Daten-API-Generator (DATA API Builder, DAB) hilft Unternehmen dabei, Compliance-, Governance- und Observability-Anforderungen zu erfüllen. Im Gegensatz zu Application Insights (die sich auf APM konzentrieren), bietet Log Analytics eine umfassendere Protokollaggregation mit Kusto Query Language (KQL)-Unterstützung.

Voraussetzungen

• Vorhandene DAB-Konfigurationsdatei.
• Azure-Abonnement mit Berechtigungen zum Erstellen von Log Analytics-Ressourcen.
• Azure Log Analytics-Arbeitsbereich mit:
  • Eine benutzerdefinierte Tabelle (endet in _CL)
  • Eine Datensammlungsregel (DATA Collection Rule, DCR)
  • Ein Datensammlungsendpunkt (DATA Collection Endpoint, DCE)
• Verwaltete Identität auf Ihrem DAB-Host aktiviert (Azure App Service, Container-Apps, VM usw.).
• CLI des Daten-API-Erstellers. Installieren der CLI

Einrichten von Azure Log Analytics-Ressourcen

Erstellen Sie vor dem Konfigurieren von DAB die erforderlichen Azure-Ressourcen.

Erstellen eines Log Analytics-Arbeitsbereichs

Azure-Portal

1. Navigieren Sie zu Azure Portal>Log Analytics-Arbeitsbereichen.
2. Wählen Sie + Erstellen aus.
3. Wählen Sie Ihr Abonnement, Ihre Ressourcengruppe und Ihre Region aus.
4. Geben Sie einen Arbeitsbereichsnamen an.
5. Wählen Sie Bewerten + erstellen>Erstellen aus.

Azure CLI

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

Erstellen einer benutzerdefinierten Tabelle

Benutzerdefinierte Tabellen für die Protokollaufnahme-API müssen mit enden _CL.

1. Navigieren Sie in Ihrem Log Analytics-Arbeitsbereich zu "Tabellen".
2. Select + Erstellen>Neues benutzerdefiniertes Protokoll (DCR-basiert).
3. Geben Sie den Tabellennamen ein (z. B DabLogs_CL. ).
4. Definieren Sie das Schema mit den folgenden Spalten:
   • Time (Datum/Zeit)
   • LogLevel (Zeichenfolge)
   • Message (Zeichenfolge)
   • Component (Zeichenfolge)
   • Identifier (Zeichenfolge)
5. Wählen Sie "Erstellen" aus.

Erstellen eines Datensammlungsendpunkts (DATA Collection Endpoint, DCE)

Azure-Portal

1. Navigieren Sie zu Monitor>Datensammlungsendpunkte.
2. Wählen Sie + Erstellen aus.
3. Wählen Sie Ihr Abonnement, Ihre Ressourcengruppe und Ihre Region aus.
4. Geben Sie einen Namen an (z. B my-dce. ).
5. Wählen Sie Bewerten + erstellen>Erstellen aus.
6. Kopieren Sie die URL des Protokollaufnahme-Endpunkts (z. B. https://my-dce.eastus-1.ingest.monitor.azure.com).

Azure CLI

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

Rufen Sie den Endpunkt ab:

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

Erstellen einer Datensammlungsregel (Data Collection Rule, DCR)

1. Navigieren Sie zu Monitor>Datensammlungsregeln.
2. Wählen Sie + Erstellen aus.
3. Wählen Sie "Abonnement", "Ressourcengruppe", "Region" aus.
4. Geben Sie einen Namen an (z. B my-dcr. ).
5. Wählen Sie in Datenquellenbenutzerdefinierte Textprotokolle aus.
6. Konfigurieren:
   • Datensammlungsendpunkt: Wählen Sie Ihren DCE aus.
   • Ziel: Ihr Log Analytics-Arbeitsbereich.
   • Tabelle: Ihre benutzerdefinierte Tabelle (DabLogs_CL).
7. Wählen Sie Bewerten + erstellen>Erstellen aus.
8. Kopieren Sie die unveränderliche ID (beginnt mit dcr-).

Konfigurieren der Authentifizierung

DAB verwendet Azure Managed Identity , um sich bei Log Analytics zu authentifizieren. In Ihrer Konfiguration werden keine Anmeldeinformationen gespeichert.

Verwaltete Identität aktivieren

App-Dienst

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

Container-Anwendungen

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

Berechtigungen zuweisen

Gewähren Sie Ihrer verwalteten Identität die Rolle Monitoring Metrics Publisher im 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

Von Bedeutung

Ohne diese Rollenzuweisung kann DAB keine Protokolle auch mit der richtigen Konfiguration an Log Analytics senden.

Konfigurieren von Log Analytics

Fügen Sie einen azure-log-analytics Abschnitt unter runtime.telemetry in Ihrer Konfigurationsdatei hinzu.

{
  "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"
        }
      }
    }
  }
}

Konfigurationseigenschaften

Eigentum	Description	Standard	Constraints
enabled	Aktivieren oder Deaktivieren der Log Analytics-Integration.	false	Boolean
dab-identifier	Eindeutige Zeichenfolge zum Identifizieren von Protokolleinträgen aus dieser DAB-Instanz.	DabLogs	Beliebige Zeichenfolge
flush-interval-seconds	Wie oft (in Sekunden) Protokolle an Log Analytics gesendet werden.	5	Muss 0 sein >
auth.custom-table-name	Benutzerdefinierter Tabellenname im Log Analytics-Arbeitsbereich.	(erforderlich)	Muss enden mit _CL
auth.dcr-immutable-id	Unveränderliche ID Ihrer Datensammlungsregel.	(erforderlich)	Beginnt mit dcr-
auth.dce-endpoint	Endpunkt-URL der Datensammlung.	(erforderlich)	HTTPS-URL

Command-line

Konfigurieren Sie Log Analytics über dab configure.

Log Analytics aktivieren

Bash

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

Eingabeaufforderung

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

Festlegen des DAB-Bezeichners

Bash

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

Eingabeaufforderung

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

Festlegen des Intervalls für das Leeren

Bash

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

Eingabeaufforderung

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

Festlegen des benutzerdefinierten Tabellennamens

Bash

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

Eingabeaufforderung

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

Festlegen der unveränderlichen DCR-ID

Bash

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

Eingabeaufforderung

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

Festlegen des DCE-Endpunkts

Bash

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

Eingabeaufforderung

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

Ausführen von DAB

Starten Sie DAB mit Ihrer Konfigurationsdatei:

dab start

Überprüfen Sie die DAB-Startprotokolle auf:

Azure Log Analytics is enabled.

Funktionsweise

Wenn Log Analytics aktiviert ist, DAB:

1. Authentifiziert sich bei Azure mithilfe der verwalteten Identität des Hosts.
2. Gruppiert Protokolleinträge basierend auf flush-interval-seconds.
3. Sendet Protokolle an den Datensammlungsendpunkt (DATA Collection Endpoint, DCE).
4. DCE leitet Protokolle über die Data Collection Rule (DCR) zur Transformation weiter.
5. DCR erfasst Protokolle in Ihrer benutzerdefinierten Log Analytics-Tabelle.

Datenfluss

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)

Was erfasst wird

Telemetrietyp	Quelle	Examples
Ablaufverfolgungen	ILogger Anrufe in DAB	Startprotokolle, Abfrageausführungsprotokolle, Warnungen
Errors	Ausnahmenbehandlung	Laufzeitfehler, Konfigurationsfehler, Datenbankfehler
Komponenteninformationen	DAB-Architektur	Welches Modul das Protokoll generiert hat
Instanz-ID	Konfiguration	dab-identifier Wert für die Filterung

Protokollstruktur

Jeder Protokolleintrag, der an Log Analytics gesendet wird, enthält die folgenden Felder:

Feld	Typ	Description	Example
Time	Datum/Uhrzeit	Zeitstempel (ISO 8601)	2026-01-27T14:30:00Z
LogLevel	Schnur	Protokollschweregrad	Information, WarningError
Message	Schnur	Protokollnachricht	Request completed successfully
Component	Schnur	DAB-Komponente, die das Protokoll generiert hat	Azure.DataApiBuilder.Service.Startup
Identifier	Schnur	Wert aus dab-identifier Konfiguration	my-dab-instance

Hinweis

Benutzerdefinierte Tabellenspalten in Log Analytics hängen Suffixe an: _s für Zeichenfolgen, _d für Doubles, _t für Datetimes usw.

Abfrageprotokolle in Log Analytics

1. Öffnen Sie Ihren Log Analytics-Arbeitsbereich im Azure-Portal.

2. Navigieren Sie zu Protokollen , und führen Sie eine KQL-Abfrage aus:

   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
   

Beispielabfragen

Anzahl der Protokolle nach Ebene:

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

Suchen von Fehlern in einer bestimmten Komponente:

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

Überlegungen zu Leistung und Kosten

Batchverarbeitungsverhalten

DAB fasst Protokolle in Chargen zusammen und sendet sie alle flush-interval-seconds.

• 5 Sekunden (Standard): Gute Balance für die meisten Szenarien.
• 1-2 Sekunden: Nahezu echtzeitbasierte Protokollierung (höhere API-Aufrufe, höhere Kosten).
• 10-60 Sekunden: Reduzierte API-Aufrufe, aber verzögerte Protokolle.

Kostenoptimierung

Die Log Analytics-Preise basieren auf:

1. Datenaufnahme: Pro GB aufgenommen.
2. Datenaufbewahrung: Pro GB pro Monat nach der kostenlosen Stufe.

Kosten senken:

• Erhöhen Sie flush-interval-seconds, um mehr Protokolle zu verarbeiten.
• Verwenden Sie Filter auf Protokollebene, um ausführliche Protokolle auszuschließen. Weitere Informationen finden Sie unter Anpassen der Ausführlichkeit von Logdateien.
• Legen Sie die entsprechende Datenaufbewahrung in Ihrem Log Analytics-Arbeitsbereich fest.

Beispiel: Filtern, um die Lautstärke zu reduzieren

{
  "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"
        }
      }
    }
  }
}

Dadurch werden nur Warnungs - und Fehlerprotokolle gesendet, wodurch das Volumen erheblich reduziert wird.

Beibehaltung von Daten

Die Log Analytics-Datenaufbewahrung kann pro Arbeitsbereich konfiguriert werden:

Tarif	Standardaufbewahrung	Maximale Aufbewahrung
Kostenlose Stufe	7 Tage	7 Tage
Nutzungsbasierte Bezahlung	30 Tage	730 Tage (2 Jahre)

Konfigurieren der Aufbewahrung: Log Analytics-Arbeitsbereich → Nutzung und geschätzte Kosten → Datenaufbewahrung.

Tipp

Berücksichtigen Sie für Complianceanforderungen das Archivieren älterer Protokolle in Azure Storage für eine langfristige Aufbewahrung.

Problembehandlung

Protokolle werden in Log Analytics nicht angezeigt

Symptom: DAB wird erfolgreich gestartet, aber es werden keine Protokolle in Ihrem Log Analytics-Arbeitsbereich angezeigt.

Mögliche Ursachen:

• Unvollständige Konfiguration: Überprüfen Sie die DAB-Startprotokolle auf Fehler wie Logs won't be sent to Azure Log Analytics because the Custom Table Name is not available in the config file. Überprüfen aller erforderlichen Authentifizierungseigenschaften: custom-table-name, , dcr-immutable-iddce-endpoint.

• Verwaltete Identität nicht zugewiesen: Überprüfen, ob verwaltete Identität aktiviert ist.az webapp identity show --name my-app --resource-group my-rg Überprüfen Sie die Rollenzuweisung mit az role assignment list --assignee <principal-id> --scope <dcr-id>.

• Falsche DCE-Endpunkt- oder DCR-ID: Überprüfen Sie, ob das Format des DCE-Endpunkts korrekt ist https://<dce-name>.<region>-1.ingest.monitor.azure.com. Überprüfen Sie, ob die unveränderliche DCR-ID mit dcr- beginnt.

• Benutzerdefinierte Tabelle ist nicht vorhanden: Benutzerdefinierte Tabellen müssen mit enden _CL. Das Tabellenschema muss mit der Protokollstruktur übereinstimmen.

Fehler: Flush-Intervall muss positiv sein

Ursache: flush-interval-seconds wird auf 0 oder negativer Wert festgelegt.

Lösung: Auf eine positive ganze Zahl (Minimumflush-interval-seconds) festlegen1.

DAB-Protokolle zeigen "Azure Log Analytics ist deaktiviert"

Ursache: enabled ist false oder fehlt in der Konfiguration.

Lösung: Setzen Sie enabled: true in Ihrer Konfiguration.

Log Analytics vs. Application Insights

Fähigkeit	Application Insights	Log Analytics
Fokus	Anwendungsleistungsüberwachung (APM)	Zentralisierte Protokollaggregation
Abfragesprache	KQL	KQL
Geltungsbereich	Einzelne Anwendung	Apps, VMs, Container, Azure-Ressourcen
Anwendungsfall	Leistung, Ausnahmen, Traces	Compliance, Governance, ressourcenübergreifende Korrelation
Authentifizierung	Verbindungsstring	Verwaltete Identität (über DCR/DCE)

Verwenden Sie Application Insights, wenn Sie APM-Features wie Anforderungsnachverfolgung, Abhängigkeitszuordnung und Leistungsprofilerstellung benötigen. Verwenden Sie Log Analytics, wenn Sie eine zentralisierte Protokollierung über mehrere Ressourcen mit Unternehmenscomplianceanforderungen benötigen.

Verwandte Inhalte

• Verwenden von Application Insights
• Verwenden von OpenTelemetry
• Anpassen der Ausführlichkeit von Logs
• Datensammlungsregeln in Azure Monitor
• Verwaltete Identitäten für Azure-Ressourcen