Korzystanie z usługi Azure Log Analytics w narzędziu Data API Builder

Azure Log Analytics to scentralizowana platforma rejestrowania, która agreguje dzienniki z aplikacji, zasobów platformy Azure, maszyn wirtualnych, kontenerów i nie tylko. Zintegrowanie go z narzędziem Data API Builder (DAB) pomaga przedsiębiorstwom w spełnianiu wymagań dotyczących zgodności, zarządzania oraz obserwowalności. W przeciwieństwie do usługi Application Insights (która koncentruje się na APM), usługa Log Analytics zapewnia szerszą agregację dzienników dzięki obsłudze języka KQL (Kusto Query Language).

Diagram przedstawiający przepływ telemetrii usługi Log Analytics.

Wymagania wstępne

Istniejący plik konfiguracji języka DAB.
Subskrypcja platformy Azure z uprawnieniami do tworzenia zasobów usługi Log Analytics.
Obszar roboczy usługi Azure Log Analytics z:
- Tabela niestandardowa (kończąca się na _CL)
- Reguła zbierania danych (DCR)
- Punkt końcowy zbierania danych (DCE)
Tożsamość zarządzana włączona na hoście DAB (Azure App Service, Container Apps, VM itp.).
Kreator interfejsu wiersza polecenia do API danych. Zainstaluj CLI

Konfigurowanie zasobów usługi Azure Log Analytics

Przed skonfigurowaniem języka DAB utwórz wymagane zasoby platformy Azure.

Tworzenie obszaru roboczego usługi Log Analytics

Portal Azure
"Azure CLI"

Przejdź doobszarów roboczych usługi Log Analytics w witrynie >.
Wybierz + Utwórz.
Wybierz subskrypcję, grupę zasobów i region.
Podaj nazwę obszaru roboczego.
Wybierz Przejrzyj i utwórz>Utwórz.

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

Tworzenie tabeli niestandardowej

Tabele niestandardowe dla interfejsu API zbierania dzienników muszą kończyć się ciągiem _CL.

W obszarze roboczym usługi Log Analytics przejdź do obszaru Tabele.
Wybierz + Utwórz>nowy niestandardowy dziennik (oparty na DCR).
Wprowadź nazwę tabeli (na przykład DabLogs_CL).
Zdefiniuj schemat przy użyciu następujących kolumn:
- Time (data/godzina)
- LogLevel (ciąg)
- Message (ciąg)
- Component (ciąg)
- Identifier (ciąg)
Wybierz Utwórz.

Tworzenie punktu końcowego zbierania danych (DCE)

Portal Azure
"Azure CLI"

Przejdź do obszaru Monitorowanie>punktów końcowych zbierania danych.
Wybierz + Utwórz.
Wybierz subskrypcję, grupę zasobów i region.
Podaj nazwę (na przykład my-dce).
Wybierz Przejrzyj i utwórz>Utwórz.
Skopiuj adres URL punktu końcowego pozyskiwania dzienników (na przykład https://my-dce.eastus-1.ingest.monitor.azure.com).

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

Pobierz punkt końcowy:

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

Tworzenie reguły zbierania danych (DCR)

Przejdź do Monitor>Reguły zbierania danych.
Wybierz + Utwórz.
Wybierz subskrypcję, grupę zasobów, region.
Podaj nazwę (na przykład my-dcr).
W Źródłach danych wybierz Niestandardowe dzienniki tekstowe.
Skonfiguruj
- Punkt końcowy zbierania danych: wybierz swoje DCE.
- Miejsce docelowe: Obszar roboczy usługi Log Analytics.
- Tabela: Twoja niestandardowa tabela (DabLogs_CL).
Wybierz Przejrzyj i utwórz>Utwórz.
Skopiuj niezmienny identyfikator (zaczyna się od dcr-).

Konfigurowanie uwierzytelniania

DAB używa zarządzanej tożsamości Azure do uwierzytelniania w usłudze Log Analytics. W konfiguracji nie są przechowywane żadne poświadczenia.

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

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

Przypisz uprawnienia

Udziel roli Wydawca metryk monitorowania Twojej tożsamości zarządzanej w 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

Ważne

Bez tego przypisania roli usługa DAB nie może wysyłać dzienników do usługi Log Analytics nawet z poprawną konfiguracją.

Konfigurowanie usługi Log Analytics

Dodaj sekcję azure-log-analytics w runtime.telemetry pliku konfiguracji.

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

Właściwości konfiguracji

Majątek	Description	Default	Constraints
`enabled`	Włączanie lub wyłączanie integracji usługi Log Analytics.	`false`	logiczny
`dab-identifier`	Unikatowy ciąg identyfikujący wpisy dziennika tego wystąpienia DAB.	`DabLogs`	Dowolny ciąg
`flush-interval-seconds`	Jak często (w sekundach) dzienniki są przesyłane do usługi Log Analytics.	`5`	Musi mieć wartość > 0
`auth.custom-table-name`	Domyślna nazwa tabeli w przestrzeni roboczej Log Analytics.	(wymagane)	Musi kończyć się `_CL`
`auth.dcr-immutable-id`	Niezmienny identyfikator reguły zbierania danych.	(wymagane)	Rozpoczyna się od `dcr-`
`auth.dce-endpoint`	Adres URL punktu końcowego zbierania danych.	(wymagane)	HTTPS URL

Command-line

Skonfiguruj usługę Log Analytics za pomocą polecenia dab configure.

Włączanie usługi Log Analytics

Bash
Wiersz polecenia

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

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

Ustaw identyfikator DAB

Bash
Wiersz polecenia

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

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

Ustawianie interwału opróżniania

Bash
Wiersz polecenia

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

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

Ustawianie niestandardowej nazwy tabeli

Bash
Wiersz polecenia

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

Ustawianie niezmiennego identyfikatora dcR

Bash
Wiersz polecenia

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

Ustawianie punktu końcowego DCE

Bash
Wiersz polecenia

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

Uruchom DAB

Uruchom program DAB przy użyciu pliku konfiguracji:

dab start

Sprawdź dzienniki uruchamiania usługi DAB pod kątem:

Azure Log Analytics is enabled.

Jak to działa

Kiedy usługa Log Analytics jest włączona, DAB:

Uwierzytelnia się na platformie Azure za pomocą zarządzanej tożsamości hosta.
Grupuje wpisy dziennika na podstawie flush-interval-seconds.
Wysyła dzienniki do punktu końcowego zbierania danych (DCE).
DCE kieruje dzienniki przez regułę zbierania danych (DCR) w celu przekształcenia.
Usługa DCR wczytuje dzienniki do niestandardowej tabeli Log Analytics.

Przepływ danych

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)

Co jest przechwytywane

Typ telemetrii	Źródło	Przykłady
Traces	`ILogger` wywołania w języku DAB	Dzienniki uruchamiania, dzienniki wykonywania zapytań, ostrzeżenia
Errors	Obsługa wyjątków	Błędy środowiska uruchomieniowego, błędy konfiguracji, błędy bazy danych
Informacje o składniku	Wewnętrzne elementy języka DAB	Który moduł wygenerował dziennik
Identyfikator wystąpienia	Konfiguracja	`dab-identifier` wartość filtrowania

Struktura dziennika

Każdy wpis dziennika wysłany do usługi Log Analytics zawiera następujące pola:

(No changes needed)	Typ	Description	Example
`Time`	data/godzina	Sygnatura czasowa (ISO 8601)	`2026-01-27T14:30:00Z`
`LogLevel`	ciąg	Poziom ważności logów	`Information`, `WarningError`
`Message`	ciąg	Wiadomość logu	`Request completed successfully`
`Component`	ciąg	Składnik DAB, który wygenerował dziennik	`Azure.DataApiBuilder.Service.Startup`
`Identifier`	ciąg	Wartość z `dab-identifier` konfiguracji	`my-dab-instance`

Uwaga / Notatka

Niestandardowe kolumny tabel w usłudze Log Analytics mają sufiksy: _s dla ciągów znaków, _d dla liczb zmiennoprzecinkowych, _t dla dat/czasów itp.

Wykonywanie zapytań dotyczących dzienników w usłudze Log Analytics

Otwórz obszar roboczy usługi Log Analytics w witrynie Azure Portal.

Przejdź do Dzienniki i uruchom zapytanie 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

Przykłady zapytań

Zlicz logi według poziomu

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

Znajdź błędy w określonym składniku:

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

Zagadnienia dotyczące wydajności i kosztów

Zachowanie przetwarzania wsadowego

DAB grupuje dzienniki i wysyła je co flush-interval-seconds:

5 sekund (wartość domyślna): dobra równowaga dla większości scenariuszy.
1–2 sekundy: rejestrowanie niemal w czasie rzeczywistym (wyższe wywołania interfejsu API, wyższy koszt).
10–60 sekund: zmniejszona liczba wywołań API, ale opóźnione logi.

Optymalizacja kosztów

Cennik usługi Log Analytics jest oparty na:

Pozyskiwanie danych: za każdy zaimportowany GB.
Przechowywanie danych: za GB miesięcznie po bezpłatnym poziomie.

Obniżanie kosztów:

Zwiększ flush-interval-seconds, aby zgrupować więcej logów.
Użyj filtrów poziomu dziennika, aby wykluczyć szczegółowe dzienniki. Aby uzyskać więcej informacji, zobacz Dostosowywanie szczegółowości dziennika.
Ustaw odpowiednie przechowywanie danych w obszarze roboczym usługi Log Analytics.

Przykład: filtrowanie w celu zmniejszenia woluminu

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

Spowoduje to wysłanie tylko dzienników ostrzeżeń i błędów , co znacznie zmniejsza wolumin.

Przechowywanie danych

Przechowywanie danych usługi Log Analytics można skonfigurować dla każdego obszaru roboczego:

Warstwa	Domyślne przechowywanie	Maksymalny okres przechowywania
warstwa Bezpłatna	7 dni	7 dni
Pay-as-you-go	30 dni	730 dni (2 lata)

Konfigurowanie przechowywania: obszar roboczy usługi Log Analytics → użycie i szacowane koszty → przechowywanie danych.

Wskazówka

W przypadku wymagań dotyczących zgodności rozważ archiwizowanie starszych dzienników w usłudze Azure Storage w celu długoterminowego przechowywania.

Rozwiązywanie problemów

Dzienniki nie są wyświetlane w usłudze Log Analytics

Objaw: DAB uruchamia się pomyślnie, ale w obszarze roboczym Log Analytics nie pojawiają się żadne dzienniki.

Możliwe przyczyny:

Niekompletna konfiguracja: Sprawdź dzienniki uruchamiania języka DAB pod kątem błędów, takich jak Logs won't be sent to Azure Log Analytics because the Custom Table Name is not available in the config file. Sprawdź wszystkie wymagane właściwości uwierzytelniania: custom-table-name, , dcr-immutable-iddce-endpoint.
Tożsamość zarządzana nie została przypisana: Sprawdź, czy tożsamość zarządzana jest włączona za pomocą polecenia az webapp identity show --name my-app --resource-group my-rg. Sprawdź przypisanie roli za pomocą az role assignment list --assignee <principal-id> --scope <dcr-id>.
Nieprawidłowy punkt końcowy DCE lub identyfikator DCR: Sprawdź, czy format punktu końcowego DCE to https://<dce-name>.<region>-1.ingest.monitor.azure.com. Sprawdź, czy identyfikator niezmienny dcR rozpoczyna się od dcr-.
Tabela niestandardowa nie istnieje: tabele niestandardowe muszą kończyć się ciągiem _CL. Schemat tabeli musi być zgodny ze strukturą dziennika.

Błąd: Interwał opróżniania musi być dodatni

Przyczyna: flush-interval-seconds jest ustawiona na 0 wartość ujemną.

Rozwiązanie: ustaw flush-interval-seconds na dodatnią liczbę całkowitą (co najmniej 1).

Dzienniki DAB pokazują, że "Azure Log Analytics jest wyłączony"

Przyczyna: enabled jest false lub brakuje jej w konfiguracji.

Rozwiązanie: Ustaw enabled: true w konfiguracji.

Log Analytics kontra Application Insights

Capability	Application Insights	Analiza dzienników
Ukierunkowanie	Monitorowanie wydajności aplikacji (APM)	Scentralizowana agregacja dzienników
Język zapytań	KQL	KQL
Scope	Pojedyncza aplikacja	Aplikacje, maszyny wirtualne, kontenery, zasoby platformy Azure
Przypadek użycia	Wydajność, wyjątki, ślady	Zgodność, ład, korelacja między zasobami
Authentication	Łańcuch połączenia	Tożsamość zarządzana (za pośrednictwem DCR/DCE)

Użyj usługi Application Insights, gdy potrzebujesz funkcji APM, takich jak śledzenie żądań, mapowanie zależności i profilowanie wydajności. Użyj usługi Log Analytics, gdy potrzebujesz scentralizowanego rejestrowania w wielu zasobach z wymaganiami dotyczącymi zgodności przedsiębiorstwa.

Sprzężenie zwrotne

Czy ta strona była pomocna?

Last updated on 2026-01-28