Korzystanie z usługi Azure Application Insights w narzędziu Data API Builder

Azure Application Insights to usługa monitorowania wydajności aplikacji (APM), która automatycznie przechwytuje żądania, ślady, wyjątki i metryki wydajności. Zintegrowanie go z narzędziem Data API Builder (DAB) ułatwia monitorowanie zachowania środowiska uruchomieniowego, diagnozowanie problemów i optymalizowanie wydajności w środowisku produkcyjnym.

Ostrzeżenie

Integracja Application Insights z DAB może mieć ograniczenia, gdy jest hostowana w aplikacjach internetowych usługi Azure App Service z powodu podwójnej instrumentacji. Usługa Application Insights najlepiej sprawdza się w języku DAB podczas samodzielnego hostowania go w kontenerach, usłudze Azure Container Apps lub usłudze Azure Kubernetes Service (AKS). Jeśli musisz użyć usługi App Service, przetestuj dokładnie lub rozważ alternatywne podejścia do monitorowania.

Wymagania wstępne

• Istniejący plik konfiguracji języka DAB.
• Zasób usługi Azure Application Insights.
• Parametry połączenia usługi Application Insights.
• Kreator interfejsu wiersza polecenia do API danych. Zainstaluj CLI

Pobieranie parametrów połączenia

Przed skonfigurowaniem DAB, uzyskaj ciąg połączenia dla Application Insights z platformy Azure.

Azure Portal

1. Przejdź do zasobu usługi Application Insights w witrynie Azure Portal.
2. Przejdź do obszaru Przegląd lub Właściwości.
3. Skopiuj parametry połączenia (a nie klucz instrumentacji).

Azure CLI

Bash

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

Wiersz polecenia

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

Format ciągu połączenia

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

Uwaga / Notatka

Użyj pełnych parametrów połączenia (nie tylko klucza instrumentacji) dla punktów końcowych specyficznych dla regionu i lepszej wydajności.

Skonfiguruj Application Insights

Dodaj sekcję application-insights w runtime.telemetry pliku konfiguracji.

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

Ta konfiguracja używa zmiennej środowiskowej dla parametrów połączenia. Zdefiniuj to w pliku .env.

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

Ostrzeżenie

Nigdy nie zatwierdzaj parametrów połączenia do kontroli źródła. Zawsze używaj zmiennych środowiskowych lub usługi Azure Key Vault.

Command-line

Skonfiguruj usługę Application Insights za pomocą polecenia dab add-telemetry.

Option	Opis
--app-insights-enabled	Włączanie lub wyłączanie usługi Application Insights (true lub false).
--app-insights-conn-string	Parametry połączenia dla usługi Application Insights.

Włącz usługę Application Insights

Bash

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

Wiersz polecenia

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

Wyłączanie usługi Application Insights

Bash

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

Wiersz polecenia

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

Uwaga / Notatka

Ustawienia usługi Application Insights używają wartości dab add-telemetry, a nie dab configure.

Uruchom DAB

Uruchom program DAB przy użyciu pliku konfiguracji:

dab start

Sprawdź dzienniki uruchamiania w celu potwierdzenia:

Application Insights telemetry is enabled with connection string from config.

Jak to działa

Gdy Application Insights jest włączone, DAB:

1. Rejestruje SDK usługi Application Insights przy użyciu AddApplicationInsightsTelemetry().
2. Rejestruje niestandardowy inicjalizator telemetrii, aby wzbogacić wszystkie dane telemetryczne o właściwości specyficzne dla DAB.
3. Konfiguruje TelemetryClient przy użyciu ciągu połączenia z konfiguracji.
4. Integruje się z logowaniem ASP.NET Core w celu przechwytywania dzienników konsoli w formie śladów.

Przepływ danych

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

Co jest przechwytywane

Typ telemetrii	Źródło	Przykłady
Requests	oprogramowanie pośredniczące ASP.NET Core	Żądania REST/GraphQL, czasy odpowiedzi, kody stanu
Traces	ILogger wywołania w języku DAB	Dzienniki uruchamiania, dzienniki wykonywania zapytań, ostrzeżenia
Exceptions	Nieobsługiwane wyjątki	Błędy środowiska uruchomieniowego, błędy konfiguracji, błędy bazy danych
Zależności	Wywołania bazy danych	Zapytania SQL, operacje usługi Azure Cosmos DB, czas trwania
Liczniki wydajności	Runtime	Użycie procesora CPU, zużycie pamięci, szybkość żądań

Wzbogacanie telemetrii

DAB automatycznie wzbogaca wszystkie dane telemetryczne Application Insights za pomocą właściwości niestandardowych:

Majątek	Opis	Przykładowa wartość
ProductName	Identyfikator agenta użytkownika języka DAB	dab-1.2.3
UserAgent	Pełny ciąg agenta użytkownika DAB	data-api-builder/1.2.3
Cloud.RoleName	Nazwa roli chmury w usłudze DAB	DataApiBuilder
Component.Version	Wersja języka DAB	1.2.3
Session.Id	Unikatowy identyfikator sesji	guid

Te właściwości pomagają filtrować i korelować dane telemetryczne specyficzne dla języka DAB w usłudze Application Insights.

Wykonywanie zapytań dotyczących telemetrii na platformie Azure

Ślady (dzienniki)

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

Mapowanie LogLevel:

Poziom Logowania	Ciężkość	Wartość
Śledzenie/debugowanie	Pełne informacje	0
Informacja	Informacja	1
Ostrzeżenie	Ostrzeżenie	2
Błąd	Błąd	3
Krytyczny	Krytyczny	4

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

Filtruj według wersji języka DAB

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

Znajdowanie wolnych zapytań GraphQL

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

Współczynnik powodzenia żądań

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

Najważniejsze powolne operacje bazy danych

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

Metryki na żywo

Metryki na żywo zapewniają monitorowanie w czasie rzeczywistym z <1 sekundowym opóźnieniem. Jest ona automatycznie włączana po skonfigurowaniu usługi Application Insights.

Uzyskiwanie dostępu do metryk na żywo

1. Otwórz zasób usługi Application Insights w witrynie Azure Portal.
2. Przejdź do Metryki na żywo w menu po lewej stronie.
3. Uruchom aplikację DAB.
4. W ciągu kilku sekund są wyświetlane dane w czasie rzeczywistym.

Co widzisz

Wskaźnik	Opis
Żądania przychodzące	Żądania REST/GraphQL na sekundę
Żądania wychodzące	Wywołania bazy danych na sekundę
Ogólna kondycja	Współczynnik powodzenia, niepowodzenia na sekundę
Pamięć/procesor CPU	Zużycie zasobów
Częstotliwość wyjątków	Wyjątki na sekundę

Wskazówka

Użyj metryk na żywo podczas programowania, aby zobaczyć natychmiastową opinię na temat żądań interfejsu API i operacji bazy danych.

Próbkowanie i przechowywanie danych

Próbkowanie adaptacyjne

Zestaw SDK usługi Application Insights automatycznie próbkowuje dane telemetryczne, gdy wolumen jest wysoki, aby zmniejszyć koszty i pozostać w granicach limitów częstotliwości. Częstotliwość próbkowania jest wyświetlana w interfejsie użytkownika usługi Application Insights.

Domyślne zachowanie:

• Niski poziom ruchu: wszystkie wysłane dane telemetryczne (100%)
• Duży ruch: Próbkowanie automatycznie zmniejsza głośność
• Utrzymywane dane reprezentatywne

Przechowywanie danych

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

Konfigurowanie przechowywania: usługa Application Insights → użycie i szacowane koszty → przechowywanie danych.

Zagadnienia dotyczące wydajności

Obciążenie telemetrii

Usługa Application Insights dodaje minimalne obciążenie:

• Pamięć: ~10–50 MB w zależności od ruchu
• Procesor CPU: <1% pod normalnym obciążeniem
• Opóźnienie: <1 ms na żądanie (asynchroniczne)

Najlepsze rozwiązania

• Użyj zmiennych środowiskowych dla parametrów połączenia.
• Wyłącz w środowisku lokalnym programowanie, jeśli nie jest to konieczne.
• Monitorowanie częstotliwości próbkowania w środowisku produkcyjnym.
• Ustaw odpowiednie przechowywanie danych, aby zarządzać kosztami.

Wyłączanie podczas programowania

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

Eksportowanie i wizualizacja

Dane telemetryczne są eksportowane za pośrednictwem zestawu SDK usługi Application Insights. SDK grupuje i okresowo wysyła dane.

Uwaga / Notatka

Zestaw SDK kontroluje czasowanie eksportu. Domyślne zachowanie wysyła dane telemetryczne w partiach co kilka sekund.

Ostrzeżenie

Efemeryczne kontenery, które szybko zamykają się, mogą zakończyć działanie przed zakończeniem eksportu. Skonfiguruj bezproblemowe okresy zamykania i unikaj agresywnego kończenia, aby zagwarantować zakończenie przesyłania danych telemetrycznych.

Ciąg połączenia a klucz instrumentacji

Używanie parametrów połączenia (zalecane)

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

Korzyści:

• Punkty końcowe specyficzne dla regionu (mniejsze opóźnienie)
• Obsługuje suwerenne chmury
• Odporne na przyszłość (zalecane podejście firmy Microsoft)

Starszy klucz instrumentacji

Firma Microsoft zaleca stosowanie ciągów połączeń dla nowych implementacji, mimo że nadal są one obsługiwane.

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

Uwaga / Notatka

Jeśli podasz tylko klucz instrumentacji, usługa Application Insights używa globalnego punktu końcowego pozyskiwania, co może mieć większe opóźnienie.

Rozwiązywanie problemów

Błąd: "Parametry połączenia usługi Application Insights nie mogą mieć wartości null lub są puste, jeśli są włączone"

Przyczyna: enabled jest ustawiona na true , ale connection-string brakuje lub jest pusta.

Rozwiązanie: podaj prawidłowe parametry połączenia podczas włączania usługi Application Insights lub ustaw wartość enabled .false

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

DAB uruchamia się, ale nie pojawia się żadna telemetria.

Sprawdź dzienniki uruchamiania dla następujących komunikatów:

Bash

dab start --LogLevel Information

Wiersz polecenia

dab start --LogLevel Information

Komunikat o powodzeniu:

Application Insights telemetry is enabled with connection string from config.

Komunikaty ostrzegawcze:

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.

Komunikat o błędzie:

Telemetry client is not initialized.

Weryfikowanie zmiennej środowiskowej

Bash

echo $app-insights-connection-string

Wiersz polecenia

echo %app-insights-connection-string%

Testowanie przy użyciu parametrów połączenia bezpośredniego

Tymczasowo użyj parametrów połączenia bezpośredniego (nie zmiennej środowiskowej), aby sprawdzić, czy parametry są prawidłowe:

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

Jeśli to zadziała, problem dotyczy ładowania zmiennych środowiskowych.

Treści powiązane

• Korzystanie z usługi Azure Log Analytics
• Korzystanie z funkcji OpenTelemetry
• Dostosowanie szczegółowości logów
• Omówienie usługi Application Insights
• Usługa Application Insights dla platformy ASP.NET Core