Použití Azure Application Insights v Tvůrci rozhraní Data API

Azure Application Insights je služba Application Performance Monitoring (APM), která automaticky zaznamenává požadavky, trasování, výjimky a metriky výkonu. Integrace s tvůrcem rozhraní DATA API (DAB) pomáhá monitorovat chování modulu runtime, diagnostikovat problémy a optimalizovat výkon v produkčním prostředí.

Výstraha

Integrace Application Insights s DAB může mít při hostování webových aplikací Azure App Service omezení kvůli dvojité instrumentaci. Application Insights funguje nejlépe s DAB, když ho sami hostujete v kontejnerech, Azure Container Apps nebo Azure Kubernetes Service (AKS). Pokud potřebujete službu App Service používat, důkladně otestujte nebo zvažte alternativní přístupy k monitorování.

Požadavky

• Existující konfigurační soubor DAB.
• Prostředek Azure Application Insights
• Připojovací řetězec pro „Application Insights“
• Rozhraní příkazového řádku pro tvorbu API dat. Instalace rozhraní příkazového řádku

Získání připojovacího řetězce

Před konfigurací DAB získejte připojovací řetězec Application Insights z Azure.

Azure Portal

1. Na webu Azure Portal přejděte ke svému prostředku Application Insights.
2. Přejděte na Přehled nebo Vlastnosti.
3. Zkopírujte připojovací řetězec (nikoli instrumentační klíč).

Azure CLI (příkazový řádek nástroje Azure)

Bash

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

Příkazový řádek

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

Formát připojovacího řetězce

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

Poznámka:

Pro koncové body specifické pro konkrétní oblast a lepší výkon použijte úplný připojovací řetězec (nejen instrumentační klíč).

Konfigurace Application Insights

Do souboru konfigurace přidejte oddíl application-insights pod runtime.telemetry.

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

Tato konfigurace používá pro připojovací řetězec proměnnou prostředí. Definujte jej v souboru .env.

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

Výstraha

Nikdy nezavádějte připojovací řetězce do správy zdrojového kódu. Vždy používejte proměnné prostředí nebo Azure Key Vault.

Command-line

Nakonfigurujte Application Insights přes dab add-telemetry.

Možnost	Popis
--app-insights-enabled	Povolte nebo zakažte Application Insights (true nebo false).
--app-insights-conn-string	Připojovací řetězec pro Application Insights

Aktivovat službu Application Insights

Bash

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

Příkazový řádek

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

Zakázání Application Insights

Bash

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

Příkazový řádek

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

Poznámka:

Nastavení Application Insights se používá dab add-telemetry, ne dab configure.

Spustit DAB

Spusťte DAB s konfiguračním souborem:

dab start

Zkontrolujte spouštěcí protokoly a zkontrolujte potvrzení:

Application Insights telemetry is enabled with connection string from config.

Jak to funguje

Když je služba Application Insights povolená, DAB:

1. Zaregistruje sadu Application Insights SDK pomocí AddApplicationInsightsTelemetry().
2. Zaregistruje vlastní inicializátor telemetrie, který rozšiřuje veškerou telemetrii o vlastnosti specifické pro DAB.
3. Konfiguruje TelemetryClient pomocí připojovacího řetězce z konfigurace.
4. Integruje se s protokolováním ASP.NET Core za účelem zachycení protokolů konzoly jako trasování.

Tok dat

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

Co se zachytí

Typ telemetrie	Zdroj	Examples
Requests	Middleware ASP.NET Core	Požadavky REST/GraphQL, doby odezvy, stavové kódy
Trasování	ILogger volání v DAB	Spouštěcí protokoly, protokoly spouštění dotazů, upozornění
Exceptions	Neošetřené výjimky	Chyby za běhu, chyby konfigurace, chyby databáze
Závislosti	Volání databáze	Dotazy SQL, operace služby Azure Cosmos DB, doba trvání
Čítače výkonu	Runtime	Využití procesoru, spotřeba paměti, frekvence požadavků

Rozšiřování telemetrie

DAB automaticky rozšiřuje veškerou telemetrii Application Insights vlastními vlastnostmi:

Vlastnictví	Popis	Příklad hodnoty
ProductName	Identifikátor uživatelského agenta DAB	dab-1.2.3
UserAgent	Úplný řetězec uživatelského agenta DAB	data-api-builder/1.2.3
Cloud.RoleName	Název cloudové role DAB	DataApiBuilder
Component.Version	Verze DAB	1.2.3
Session.Id	Jedinečný identifikátor relace	guid

Tyto vlastnosti pomáhají filtrovat a korelovat telemetrii specifickou pro DAB v Application Insights.

Dotazování telemetrie v Azure

Trasování (protokoly)

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

Mapování úrovně protokolu:

LogLevel	Závažnost	Hodnota
Trasování / ladění	Zdlouhavý	0
Informace	Informace	1
Výstraha	Výstraha	2
Chyba	Chyba	3
Kritický	Kritický	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

Filtrování podle verze DAB

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

Vyhledání pomalých dotazů GraphQL

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

Míra úspěšnosti požadavků

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

Hlavní pomalé databázové operace

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

Živé metriky

Živé metriky poskytují monitorování v reálném čase s <latencí 1 sekundy. Application Insights ji povolí automaticky při konfiguraci.

Přístup k živým metrikám

1. Otevřete prostředek Application Insights na portálu Azure.
2. V nabídce vlevo přejděte na Živé metriky .
3. Spusťte aplikaci DAB.
4. Během několika sekund se zobrazí data v reálném čase.

Co vidíte

Ukazatel	Popis
Příchozí požadavky	Požadavky REST/GraphQL za sekundu
Odchozí požadavky	Volání databáze za sekundu
Celkový stav	Míra úspěšnosti, selhání za sekundu
Paměť / procesor	Využití prostředků
Rychlost výjimek	Výjimky za sekundu

Návod

Pomocí živých metrik během vývoje můžete zobrazit okamžitou zpětnou vazbu k žádostem rozhraní API a databázovým operacím.

Vzorkování a uchovávání dat

Adaptivní vzorkování

SDK pro Application Insights automaticky vzorkuje telemetrii, když je objem vysoký, aby se snížily náklady a zůstalo se v mezích limitů přenosové rychlosti. Vzorkovací frekvence se zobrazuje v uživatelském rozhraní Application Insights.

Výchozí chování:

• Nízký datový provoz: Všechna odeslaná telemetrická data (100%)
• Vysoký provoz: Vzorkování automaticky snižuje objem dat
• Zachované reprezentativní údaje

Uchovávání dat

Plán	Výchozí uchovávání	Maximální doba uchovávání
úroveň Free	90 dní	90 dní
Platba dle skutečné spotřeby	90 dní	730 dní (dva roky)

Konfigurace uchovávání informací: Application Insights → Využití a odhadované náklady → uchovávání dat.

Důležité informace o výkonu

Režijní náklady na telemetrii

Application Insights přidává minimální režii:

• Paměť: ~10–50 MB v závislosti na provozu
• PROCESOR: <1% za normálního zatížení
• Latence: <1 ms na požadavek (asynchronní)

Osvědčené postupy

• Pro připojovací řetězce použijte proměnné prostředí.
• Vypněte v místním vývoji, pokud není potřeba.
• Monitorujte vzorkovací frekvenci v produkčním prostředí.
• Nastavte vhodné uchovávání dat pro správu nákladů.

Zakázání ve vývoji

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

Export a vizualizace

Telemetrie se exportuje prostřednictvím sady Application Insights SDK. SDK dávkuje a pravidelně odesílá data.

Poznámka:

Sada SDK řídí časování exportu. Výchozí chování odesílá telemetrii v dávkách každých několik sekund.

Výstraha

Dočasné kontejnery, které rychle ukončí svůj provoz, se mohou ukončit před dokončením exportu. Nakonfigurujte řádné vypnutí oken a vyhněte se agresivnímu ukončení, abyste zajistili nevyřízené vyprázdnění telemetrie.

Připojovací řetězec vs. instrumentační klíč

Použití připojovacích řetězců (doporučeno)

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

Výhody:

• Koncové body specifické pro konkrétní oblast (nižší latence)
• Podporuje cloudová řešení s vysokou mírou suverenity.
• Budoucí zajištění (doporučený přístup Microsoftu)

Starší klíč instrumentace

I když jsou stávající metody stále podporovány, Microsoft doporučuje pro nové implementace používat připojovací řetězce.

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

Poznámka:

Pokud zadáte pouze instrumentační klíč, Application Insights použije globální koncový bod příjmu dat, který může mít vyšší latenci.

Řešení problémů

Chyba: Připojovací řetězec Application Insights nemůže být null nebo prázdný, pokud je povolený.

Příčina: enabled je nastavená na true hodnotu, ale connection-string chybí nebo je prázdná.

Řešení: Poskytněte platný připojovací řetězec při povolování Application Insights nebo nastavte enabled na false.

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

DAB se spustí, ale nezobrazí se žádná telemetrie.

Zkontrolujte, jestli spouštěcí protokoly obsahují tyto zprávy:

Bash

dab start --LogLevel Information

Příkazový řádek

dab start --LogLevel Information

Zpráva o úspěchu:

Application Insights telemetry is enabled with connection string from config.

Varovné zprávy:

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.

Chybová zpráva:

Telemetry client is not initialized.

Ověřit proměnnou prostředí

Bash

echo $app-insights-connection-string

Příkazový řádek

echo %app-insights-connection-string%

Testování pomocí přímého připojovacího řetězce

Pro ověření platnosti řetězce dočasně použijte přímý spojovací řetězec (nikoliv proměnnou prostředí):

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

Pokud tento test funguje, jedná se o problém s načítáním proměnných prostředí.

Související obsah

• dab add-telemetry Referenční informace k rozhraní příkazového řádku
• Použití Azure Log Analytics
• Použití OpenTelemetry
• Přizpůsobení podrobností protokolu
• Přehled Application Insights
• Application Insights pro ASP.NET Core