Veri API'sinde Azure Application Insights oluşturucusunu kullanma

Azure Application Insights istekleri, izlemeleri, özel durumları ve performans ölçümlerini otomatik olarak yakalayan bir Uygulama Performansı İzleme (APM) hizmetidir. Bunu Data API Builder (DAB) ile tümleştirmek çalışma zamanı davranışını izlemenize, sorunları tanılamanıza ve üretim performansını iyileştirmenize yardımcı olur.

Uyarı

DAB ile Application Insights tümleştirmesi, Azure App Service web uygulamalarında barındırıldığında, çift enstrümantasyon nedeniyle sınırlamalara sahip olabilir. Application Insights kapsayıcılarda, Azure Container Apps'te veya Azure Kubernetes Service'te (AKS) kendi kendine barındırdığınızda DAB ile en iyi şekilde çalışır. App Service kullanmanız gerekiyorsa, kapsamlı bir şekilde test edin veya alternatif izleme yaklaşımlarını göz önünde bulundurun.

Önkoşullar

• Mevcut DAB yapılandırma dosyası.
• Azure Application Insights kaynağı.
• Application Insights bağlantı dizesi.
• Veri API'si oluşturucu CLI. CLI'yi yükleme

Bağlantı dizesini alma

DAB'yi yapılandırmadan önce Azure'dan Application Insights bağlantı dizesini alın.

Azure portalı

1. Azure portalda Application Insights kaynağınıza gidin.
2. Genel Bakış'a veya Özellikler'e gidin.
3. Bağlantı Dizesini kopyalayın (İzleme Anahtarı'nı değil).

Azure Komut Satırı Arayüzü (Azure CLI)

Bash

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

Komut İstemi

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

Bağlantı dizesi biçimi

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

Uyarı

Tam bağlantı dizesini (yalnızca enstrümantasyon anahtarını değil) bölgeye özgü uç noktalar ve daha iyi performans için kullanın.

Application Insights'i Yapılandır

Yapılandırma dosyanızın altına application-insights bir runtime.telemetry bölüm ekleyin.

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

Bu yapılandırma, bağlantı dizesi için bir ortam değişkeni kullanır. Bir .env dosyada tanımlayın:

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

Uyarı

Bağlantı dizelerini hiçbir zaman kaynak denetimine işlemeyin. Ortam değişkenlerini veya Azure Key Vault'ta her zaman kullanın.

Command-line

aracılığıyla dab add-telemetryApplication Insights'ı yapılandırın.

Seçenek	Açıklama
--app-insights-enabled	Application Insights'ı (true veya ) etkinleştirin veya falsedevre dışı bırakın.
--app-insights-conn-string	Application Insights için bağlantı dizesi.

Application Insights’ı Etkinleştir

Bash

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

Komut İstemi

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

Application Insights'ı devre dışı bırakma

Bash

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

Komut İstemi

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

Uyarı

Application Insights ayarları dab add-telemetry kullanır, dab configure değil.

DAB çalıştırma

DAB'i yapılandırma dosyanızla başlatın:

dab start

Onay için başlangıç günlüklerini denetleyin:

Application Insights telemetry is enabled with connection string from config.

Nasıl çalışır?

Application Insights etkinleştirildiğinde DAB:

1. Application Insights SDK'sını AddApplicationInsightsTelemetry() kullanarak kaydeder.
2. Tüm telemetri verilerini DAB'ye özgü özelliklerle zenginleştirmek için özel bir telemetri başlatıcı kaydeder.
3. TelemetryClient, yapılandırmadan gelen bağlantı dizesiyle yapılandırılır.
4. ASP.NET Core günlüğü ile tümleştirilerek konsol günlükleri iz kaydı olarak yakalanır.

Veri akışı

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

Yakalananlar

Telemetri türü	Kaynak	Örnekler
Requests	ASP.NET Core ara yazılımı	REST/GraphQL istekleri, yanıt süreleri, durum kodları
İzler	ILogger DAB'de aramalar	Başlangıç günlükleri, sorgu yürütme günlükleri, uyarılar
Exceptions	İşlenmeyen özel durumlar	Çalışma zamanı hataları, yapılandırma hataları, veritabanı hataları
Bağımlılıklar	Veritabanı çağrıları	SQL sorguları, Azure Cosmos DB işlemleri, süre
Performans sayaçları	Çalışma zamanı	CPU kullanımı, bellek tüketimi, istek hızı

Telemetri verilerini zenginleştirme

DAB, tüm Application Insights telemetri verilerini otomatik olarak özel özelliklerle zenginleştirir:

Mülkiyet	Açıklama	Örnek değer
ProductName	DAB kullanıcı aracısı tanımlayıcısı	dab-1.2.3
UserAgent	Tam DAB kullanıcı temsilcisi dizesi	data-api-builder/1.2.3
Cloud.RoleName	DAB bulut rolü adı	DataApiBuilder
Component.Version	DAB sürümü	1.2.3
Session.Id	Benzersiz oturum tanımlayıcısı	guid

Bu özellikler, Application Insights'ta DAB'ye özgü telemetri verilerini filtrelemeye ve ilişkilendirmeye yardımcı olur.

Azure'da telemetriyi sorgulama

İzlemeler (günlükler)

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

LogLevel eşlemesi:

Log Seviyesi	Şiddet	Değer
İzleme / Hata Ayıklama	Ağır dilli	0
Bilgi	Bilgi	1
Uyarı	Uyarı	2
Hata	Hata	3
Çok Önemli	Çok Önemli	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

DAB sürümüne göre filtreleme

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

Yavaş GraphQL sorgularını bulma

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

İstek başarı oranı

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

En yavaş veritabanı işlemleri

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

Canlı Ölçümler

Canlı Ölçümler, 1 saniyelik gecikme süresiyle <gerçek zamanlı izleme sağlar. Application Insights yapılandırıldığında otomatik olarak etkinleştirilir.

Canlı Ölçümlere Erişme

1. Application Insights kaynağınızı Azure portalında açın.
2. Soldaki menüde Canlı Ölçümler'e gidin.
3. DAB uygulamanızı başlatın.
4. Saniyeler içinde gerçek zamanlı veriler görüntülenir.

Gördükleriniz

Ölçü birimi	Açıklama
Gelen İstekler	Saniye başına REST/GraphQL istekleri
Giden İstekler	Saniye başına veritabanı çağrıları
Genel Sağlık Durumu	Başarı oranı, saniye başına hatalar
Bellek / CPU	Kaynak kullanımı
Özel Durum Oranı	Saniye başına istisnalar

Tavsiye

API istekleri ve veritabanı işlemleriyle ilgili anında geri bildirim görmek için geliştirme sırasında Canlı Ölçümler'i kullanın.

Örnekleme ve veri saklama

Uyarlamalı örnekleme

Application Insights SDK'sı, maliyetleri azaltmak ve hız sınırları içinde kalmak için hacim yüksek olduğunda telemetriyi otomatik olarak örnekler. Örnekleme oranı Application Insights kullanıcı arabiriminde gösterilir.

Varsayılan davranış:

• Düşük trafik: Tüm telemetri gönderildi (100%)
• Yüksek trafik: Örnekleme otomatik olarak hacmi azaltır
• Korunan temsili veriler

Veri muhafazası

Tasarı	Varsayılan saklama	En fazla saklama
Ücretsiz seviye	90 gün	90 gün
Pay-as-you-go	90 gün	730 gün (2 yıl)

Saklamayı yapılandırma: Application Insights → Kullanımı ve tahmini maliyetler → Veri Saklama.

Performansla ilgili dikkat edilmesi gerekenler

Telemetri ek yükü

Application Insights minimum ek yük ekler:

• Bellek: Trafiğe bağlı olarak yaklaşık 10-50 MB
• CPU: <Normal yük altında 1%
• Gecikme süresi: <İstek başına 1ms (zaman uyumsuz)

En iyi yöntemler

• Bağlantı dizeleri için ortam değişkenlerini kullanın.
• Yerel geliştirmede gerekli değilse devre dışı bırakın.
• Üretimdeki örnekleme hızını izleyin.
• Maliyetleri yönetmek için uygun veri saklamayı ayarlayın.

Geliştirme aşamasında devre dışı bırakma

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

Dışarı aktarma ve görselleştirme

Telemetri, Application Insights SDK'sı aracılığıyla dışarı aktarılır. SDK düzenli aralıklarla verileri toplu işleyip gönderir.

Uyarı

SDK dışarı aktarma zamanlamasını denetler. Varsayılan davranış, telemetriyi birkaç saniyede bir toplu olarak gönderir.

Uyarı

Hızlı bir şekilde kapanan kısa ömürlü kapsayıcılar dışarı aktarma işlemi tamamlanmadan önce çıkabilir. Bekleyen telemetri temizlemelerini sağlamak için düzgün kapatma pencerelerini yapılandırın ve agresif sonlandırmadan kaçının.

Bağlantı dizesi ile izleme anahtarı karşılaştırması

Bağlantı dizelerini kullanma (önerilen)

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

Avantajlar:

• Bölgeye özgü uç noktalar (daha düşük gecikme süresi)
• Bağımsız bulutları destekler
• Geleceğe dönük (Microsoft'un önerilen yaklaşımı)

Eski enstrümantasyon anahtarı

Destek almaya devam ederken, Microsoft yeni uygulamalar için bağlantı dizeleri önerir.

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

Uyarı

Yalnızca bir araçsal anahtar sağlarsanız Application Insights, daha yüksek gecikme süresine sahip olabilecek genel alım uç noktasını kullanır.

Sorun giderme

Hata: "Application Insights bağlantı dizesi etkinse null ya da boş bırakılamaz"

Neden: enabled olarak ayarlanmış true ancak connection-string eksik veya boş.

Çözüm: Application Insights'ı etkinleştirirken geçerli bir bağlantı dizesi sağlayın veya enabled olarak false ayarlayın.

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

DAB başlatılır ancak telemetri görüntülenmez

Başlangıç günlüklerinde bu iletileri kontrol edin.

Bash

dab start --LogLevel Information

Komut İstemi

dab start --LogLevel Information

Başarı iletisi:

Application Insights telemetry is enabled with connection string from config.

Uyarı iletileri:

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.

Hata iletisi:

Telemetry client is not initialized.

Ortam değişkenlerini doğrulama

Bash

echo $app-insights-connection-string

Komut İstemi

echo %app-insights-connection-string%

Doğrudan bağlantı dizesiyle test edin

Dizenin geçerli olduğunu doğrulamak için geçici olarak bir doğrudan bağlantı dizesi (ortam değişkeni değil) kullanın:

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

Bu işe yararsa, sorun ortam değişkeni yüklemesiyle ilgilidir.

İlgili içerik

• Azure Log Analytics'i kullanma
• OpenTelemetry kullanın
• Günlük ayrıntı düzeyini özelleştirme
• Application Insights'a genel bakış
• ASP.NET Core için Application Insights