Azure Cosmos DB ve .NET için performans ipuçları

  • Şunlara uygulanır: ✅ NoSQL

Azure Cosmos DB, garantili gecikme süresi ve aktarım hızı düzeyleriyle sorunsuz bir şekilde ölçeklendirilen hızlı, esnek bir dağıtılmış veritabanıdır. Azure Cosmos DB ile veritabanınızı ölçeklendirmek için büyük mimari değişiklikleri yapmanız veya karmaşık kod yazmanız gerekmez. Ölçek büyütme ve küçültme, tek bir API çağrısı yapmak kadar kolaydır. Daha fazla bilgi edinmek için kapsayıcı aktarım hızı sağlama veya veritabanı aktarım hızı sağlama kısmına bakın.

Azure Cosmos DB'ye ağ çağrıları aracılığıyla erişildiğinden, SQL .NET SDK'sını kullanırken en yüksek performansı elde etmek için istemci tarafı iyileştirmeleri yapabilirsiniz.

Veritabanı performansınızı geliştirmeye çalışıyorsanız, aşağıdaki bölümlerde sunulan seçenekleri göz önünde bulundurun.

Barındırma önerileri

Sunucu tarafı çöp toplamayı aç

Çöp toplama sıklığını azaltmak bazı durumlarda yardımcı olabilir. .NET'te gcServer'ı.

İstemci iş yükünüzün ölçeğini genişletme

Yüksek aktarım hızı düzeylerinde veya saniyede 50.000 İstek Biriminden (RU/sn) daha yüksek hızlarda test yapıyorsanız, bilgisayarın CPU veya ağ kullanımında sınıra ulaşması nedeniyle istemci uygulaması bir iş yükü darboğazı olabilir. Bu noktaya ulaşırsanız, istemci uygulamalarınızı birden çok sunucuya yayarak Azure Cosmos DB hesabınızı daha da genişletebilirsiniz.

Note

Yüksek CPU kullanımı gecikme süresinin artmasına ve istek zaman aşımı özel durumlarına neden olabilir.

Meta veri işlemleri

Öğe işlemi yapmadan önce ya da sık erişilen yolda Create...IfNotExistsAsync veya Read...Async çağırarak bir veritabanının veya kapsayıcının mevcut olduğunu doğrulamayın. Doğrulama yalnızca gerekli olduğunda, bunların silinmesini bekliyorsanız (aksi takdirde gerekli değildir) uygulama başlangıcında yapılmalıdır. Bu meta veri işlemleri fazladan uçtan uca gecikme süresi oluşturur, SLA'sı yoktur ve veri işlemleri gibi ölçeklendirilmeyen kendi ayrı sınırlamaları vardır.

Loglama ve izleme

Bazı ortamlarda .NET DefaultTraceListener etkindir. DefaultTraceListener, yüksek CPU ve G/Ç performans sorunlarına neden olan üretim ortamlarında performans sorunları oluşturur. Üretim ortamlarında TraceListeners'dan kaldırarak uygulamanız için DefaultTraceListener'ın devre dışı olduğundan emin olun.

Algılandığında, 3.23.0'dan büyük SDK sürümleri onu otomatik olarak kaldırır. Eski sürümlerde, aşağıdaki komutları kullanarak kaldırabilirsiniz:

if (!Debugger.IsAttached)
{
    Type defaultTrace = Type.GetType("Microsoft.Azure.Cosmos.Core.Trace.DefaultTrace,Microsoft.Azure.Cosmos.Direct");
    TraceSource traceSource = (TraceSource)defaultTrace.GetProperty("TraceSource").GetValue(null);
    traceSource.Listeners.Remove("Default");
    // Add your own trace listeners
}

Yüksek kullanılabilirlik

Azure Cosmos DB'de yüksek kullanılabilirliği yapılandırma hakkında genel yönergeler için bkz . Azure Cosmos DB'de yüksek kullanılabilirlik.

Veritabanı platformunda iyi bir temel kuruluma ek olarak, kesinti senaryolarında yardımcı olabilecek .NET SDK'sının kendisinde uygulanabilecek belirli teknikler vardır. Eşik tabanlı kullanılabilirlik stratejisi ve bölüm düzeyi devre kesici iki önemli stratejidir.

Eşik tabanlı kullanılabilirlik stratejisi

Eşik tabanlı kullanılabilirlik stratejisi, ikincil bölgelere paralel okuma istekleri göndererek (içinde ApplicationPreferredRegionstanımlandığı gibi) ve en hızlı yanıtı kabul ederek kuyruk gecikme süresini ve kullanılabilirliğini geliştirebilir. Bu yaklaşım, bölgesel kesintilerin veya yüksek gecikme süresi koşullarının uygulama performansı üzerindeki etkisini önemli ölçüde azaltabilir.

Örnek yapılandırma:

Bunu yapılandırmak için CosmosClientBuilder kullanılabilir.

CosmosClient client = new CosmosClientBuilder("connection string")
    .WithApplicationPreferredRegions(
        new List<string> { "East US", "East US 2", "West US" } )
    .WithAvailabilityStrategy(
        AvailabilityStrategy.CrossRegionHedgingStrategy(
        threshold: TimeSpan.FromMilliseconds(500),
        thresholdStep: TimeSpan.FromMilliseconds(100)
     ))
    .Build();

Ya da seçenekleri yapılandırarak ve bu seçenekleri 'ye CosmosClientekleyerek:

CosmosClientOptions options = new CosmosClientOptions()
{
    AvailabilityStrategy
     = AvailabilityStrategy.CrossRegionHedgingStrategy(
        threshold: TimeSpan.FromMilliseconds(500),
        thresholdStep: TimeSpan.FromMilliseconds(100)
     )
      ApplicationPreferredRegions = new List<string>() { "East US", "East US 2", "West US"},
};

CosmosClient client = new CosmosClient(
    accountEndpoint: "account endpoint",
    authKeyOrResourceToken: "auth key or resource token",
    clientOptions: options);

Nasıl çalışır:

  1. İlk istek: T1 zamanında, birincil bölgeye (örneğin, Doğu ABD) bir okuma isteği yapılır. SDK, 500 milisaniyeye ( threshold değer) kadar yanıt bekler.

  2. İkinci istek: Birincil bölgeden 500 milisaniye içinde yanıt alınmazsa, bir sonraki tercih edilen bölgeye paralel istek gönderilir (örneğin, Doğu ABD 2).

  3. Üçüncü istek: Birincil veya ikincil bölge 600 milisaniye (500 ms + 100 ms, thresholdStep değer) içinde yanıt vermezse, SDK tercih edilen üçüncü bölgeye (örneğin, Batı ABD) başka bir paralel istek gönderir.

  4. En hızlı yanıt kazanır: İlk olarak hangi bölge yanıt veriyorsa, bu yanıt kabul edilir ve diğer paralel istekler yoksayılır.

Note

İlk tercih edilen bölge geçici olmayan bir hata durum kodu (örneğin, belge bulunamadı, yetkilendirme hatası veya çakışma) döndürürse, kullanılabilirlik stratejisinin bu senaryoda herhangi bir avantajı olmadığından işlemin kendisi hızlı başarısız olur.

Bölüm düzeyi devre kesici

Bölüm düzeyi devre kesici (PPCB), .NET SDK'sında iyi durumda olmayan fiziksel bölümleri izleyerek kullanılabilirliği ve gecikme süresini geliştiren bir özelliktir. Etkinleştirildiğinde, isteklerin daha sağlıklı bölgelere yönlendirilmesine yardımcı olur ve bölgesel veya bölüme özgü sorunlardan kaynaklanan art arda hataları önler. Bu özellik arka uç tarafından tetiklenen yük devretmeden bağımsızdır ve ortam değişkenleri aracılığıyla denetlenmektedir.

Bu özellik varsayılan olarak devre dışıdır, ancak bölüm düzeyi yük devretme etkinleştirildiğinde otomatik olarak etkinleştirilir .

Nasıl çalışır?

  1. Hata algılama: , 503 Service Unavailableveya iptal belirteçleri gibi 408 Request Timeoutbelirli hatalar gözlemlendiğinde, SDK bir bölüm için ardışık hataları sayar.
  2. Yük devretme tetikleniyor: Yapılandırılmış ardışık hata eşiğine ulaşıldıktan sonra SDK, bu bölüm anahtarı aralığına yönelik istekleri kullanarak GlobalPartitionEndpointManagerCore.TryMarkEndpointUnavailableForPartitionKeyRangebir sonraki tercih edilen bölgeye yönlendirir.
  3. Arka Plan Kurtarma: Yük devretme sırasında, dört çoğaltmanın tümüne bağlanmaya çalışılarak başarısız bölümün durumunu düzenli aralıklarla yeniden değerlendirmek için bir arka plan görevi başlatılır. SDK, sağlıklı duruma geri döndüğünde devre dışı bırakmayı kaldırır ve birincil bölgeye geri döner.

Hesap türüne göre davranış

  • Tek bölgeli yazma (tek ana öğe): Yalnızca okuma istekleri PPCB yük devretme mantığına katılır.
  • Çok bölgeli yazma (çoklu ana makine):Hem okuma hem de yazma istekleri PPCB yük devretme mantığını kullanır.

Yapılandırma seçenekleri

PPCB'yi yapılandırmak için aşağıdaki ortam değişkenlerini kullanın:

Ortam değişkeni Description Varsayılan
AZURE_COSMOS_CIRCUIT_BREAKER_ENABLED PPCB özelliğini etkinleştirir veya devre dışı bırakır. false
AZURE_COSMOS_PPCB_CONSECUTIVE_FAILURE_COUNT_FOR_READS Yük devretmeyi tetikleyen ardışık okuma hataları. 10
AZURE_COSMOS_PPCB_CONSECUTIVE_FAILURE_COUNT_FOR_WRITES Arka arkaya yazma hataları, yedekleme işlemini tetikler. 5
AZURE_COSMOS_PPCB_ALLOWED_PARTITION_UNAVAILABILITY_DURATION_IN_SECONDS Bölüm durumunu yeniden değerlendirmeden önceki süre. 5 Saniye
AZURE_COSMOS_PPCB_STALE_PARTITION_UNAVAILABILITY_REFRESH_INTERVAL_IN_SECONDS Bölüm durumunun arka plan yenileme aralığı. 60 Saniye

Note

SDK şu anda okumalar için güvenilir bir geri dönüş tetikleyicisine sahip değildir. Bunun yerine, arka plan sağlık kontrol sistemi, dört replikanın da yanıt verdiği durumda orijinal bölgeyi kademeli olarak yeniden etkinleştirmeyi dener.

Kullanılabilirlik iyileştirmelerini karşılaştırma

  • Eşik tabanlı kullanılabilirlik stratejisi:

    • Avantaj: İkincil bölgelere paralel okuma istekleri göndererek kuyruk gecikme süresini azaltır ve ağ zaman aşımlarına neden olan istekleri önceden başlatarak kullanılabilirliği artırır.
    • Takas: Eşiklerin ihlal edildiği dönemlerde, ek paralel bölgeler arası istekler nedeniyle devre kesiciye kıyasla ilave İstek Birimleri (RU) maliyetlerine yol açar.
    • Kullanım örneği: Gecikme süresini azaltmanın kritik öneme sahip olduğu ve bazı ek maliyetlerin (hem RU ücreti hem de istemci CPU baskısı açısından) kabul edilebilir olduğu okuma yoğunluklu iş yükleri için idealdir. Yazma işlemleri, bir kez etkili olmayan yazma yeniden deneme ilkesine kabul edilirse ve hesapta çok bölgeli yazma işlemleri varsa da yararlı olabilir.

  • Bölüm düzeyi devre kesici:

    • Avantaj: İyi durumda olmayan bölümlerden kaçınarak isteklerin daha sağlıklı bölgelere yönlendirilmesini sağlayarak kullanılabilirliği ve gecikme süresini artırır.
    • Ödünleşim: Daha fazla RU maliyetine neden olmaz, ancak ağ zaman aşımlarına yol açan talepler için bazı başlangıç kullanılabilirlik kayıplarına yine de yol açabilir.
    • Kullanım örneği: Özellikle aralıklı olarak iyi durumda olmayan bölümlerle ilgilenirken tutarlı performansın önemli olduğu yoğun yazma veya karma iş yükleri için idealdir.

Okuma ve yazma kullanılabilirliğini geliştirmek ve kuyruk gecikme süresini azaltmak için her iki strateji de birlikte kullanılabilir. Bölüm düzeyindeki devre kesici, paralel istekler gerçekleştirmeye gerek kalmadan, replikaların yavaş çalışmasına neden olabilecekler de dahil olmak üzere, çeşitli geçici hata senaryolarını yönetebilir. Ek olarak, ek RU maliyeti kabul edilebilirse eşik tabanlı kullanılabilirlik stratejisi eklemek kuyruk gecikme süresini daha da en aza indirir ve kullanılabilirlik kaybını ortadan kaldırır.

Geliştiriciler bu stratejileri uygulayarak uygulamalarının dayanıklı kalmasını, yüksek performansı korumasını ve bölgesel kesintiler veya yüksek gecikme süresi koşulları sırasında bile daha iyi bir kullanıcı deneyimi sunmasını sağlayabilir.

Hariç tutulan bölgeler

Hariç tutulan bölgeler özelliği, istek başına belirli bölgeleri tercih ettiğiniz konumların dışında tutmanıza olanak tanıyarak istek yönlendirmesi üzerinde ayrıntılı denetim sağlar. Bu özellik Azure Cosmos DB .NET SDK sürüm 3.37.0 ve üzeri sürümlerde kullanılabilir.

Başlıca avantajlar:

  • İşleme hızı sınırlama: 429 (Çok Fazla İstek) yanıtıyla karşılaştığınızda, istekleri otomatik olarak kullanılabilir aktarım hızına sahip alternatif bölgelere yönlendirin
  • Hedeflenen yönlendirme: Diğer tüm bölgeleri dışlayarak isteklerin belirli bölgelerden sunulduğundan emin olun
  • Tercih edilen sırayı atla: Ayrı istemciler oluşturmadan tek tek istekler için varsayılan tercih edilen bölgeler listesini geçersiz kıl

Configuration:

Dışlanan bölgeler, şu özellik kullanılarak ExcludeRegions istek düzeyinde yapılandırılabilir:

CosmosClientOptions clientOptions = new CosmosClientOptions()
{
    ApplicationPreferredRegions = new List<string> {"West US", "Central US", "East US"}
};

CosmosClient client = new CosmosClient(connectionString, clientOptions);

Database db = client.GetDatabase("myDb");
Container container = db.GetContainer("myContainer");

//Request will be served out of the West US region
await container.ReadItemAsync<dynamic>("item", new PartitionKey("pk"));

//By using ExcludeRegions, we are able to bypass the ApplicationPreferredRegions list
// and route a request directly to the East US region
await container.ReadItemAsync<dynamic>(
  "item", 
  new PartitionKey("pk"),
  new ItemRequestOptions()
  {
    ExcludeRegions = new List<string>() { "West US", "Central US" }
  });

Kullanım örneği - hız sınırlamasını işleme:

ItemResponse<CosmosItem> item;
item = await container.ReadItemAsync<CosmosItem>("id", partitionKey);

if (item.StatusCode == HttpStatusCode.TooManyRequests)
{
    ItemRequestOptions requestOptions = new ItemRequestOptions()
    {
        ExcludeRegions = new List<string>() { "East US" }
    };

    item = await container.ReadItemAsync<CosmosItem>("id", partitionKey, requestOptions);
}

Bu özellik sorgular ve diğer işlemlerle de çalışır:

QueryRequestOptions queryRequestOptions = new QueryRequestOptions()
{
    ExcludeRegions = new List<string>() { "East US" }
};

using (FeedIterator<CosmosItem> queryFeedIterator = container.GetItemQueryIterator<CosmosItem>(
    queryDefinition, 
    requestOptions: queryRequestOptions))
{
    while(queryFeedIterator.HasMoreResults)
    {
        var item = await queryFeedIterator.ReadNextAsync();
    }
}

Tutarlılık ve kullanılabilirlik arasında ince ayar

Hariç tutulan bölgeler özelliği, uygulamanızdaki tutarlılık ve kullanılabilirlik dengelemesi için ek bir mekanizma sağlar. Bu özellik, gereksinimlerin işletim koşullarına göre kayabileceği dinamik senaryolarda özellikle değerlidir:

Dinamik kesinti işleme: Birincil bölgede kesinti yaşandığında ve bölüm düzeyinde devre kesici eşikleri yetersiz olduğunda, hariç tutulan bölgeler kod değişikliği veya uygulama yeniden başlatması olmadan anında yük devretmeye olanak tanır. Bu, bölgesel sorunlara otomatik devre kesici etkinleştirmesi beklemeye kıyasla daha hızlı yanıt sağlar.

Koşullu tutarlılık tercihleri: Uygulamalar, işletim durumuna göre farklı tutarlılık stratejileri uygulayabilir:

  • Kararlı durum: Birincil bölge dışındaki tüm bölgeleri hariç tutarak tutarlı okumaların önceliğini belirleme ve olası kullanılabilirlik maliyetinde veri tutarlılığı sağlama
  • Kesinti senaryoları: Bölgeler arası yönlendirmeye izin vererek, sürekli hizmet kullanılabilirliği karşılığında olası veri gecikmesini kabul ederek katı tutarlılık yerine kullanılabilirliği destekleyin

Bu yaklaşım, dış mekanizmaların (trafik yöneticileri veya yük dengeleyiciler gibi) yük devretme kararlarını düzenlemesine olanak tanırken uygulama, bölge dışlama desenleri aracılığıyla tutarlılık gereksinimleri üzerinde denetim sahibi olur.

Tüm bölgeler dışlandığında istekler birincil/hub bölgesine yönlendirilir. Bu özellik sorgular da dahil olmak üzere tüm istek türleriyle çalışır ve esnek yönlendirme davranışı elde ederken tek istemci örneklerini korumak için özellikle yararlıdır.

Networking

Bağlantı ilkesi: Doğrudan bağlantı modunu kullanma

.NET V3 SDK varsayılan bağlantı modu TCP protokolü ile doğrudan yapılır. Bağlantı modunu CosmosClient örneğini CosmosClientOptions içinde oluştururken yapılandırırsınız. Farklı bağlantı seçenekleri hakkında daha fazla bilgi edinmek için bağlantı modları makalesine bakın.

CosmosClient client = new CosmosClient(
  "<nosql-account-endpoint>",
  tokenCredential
  new CosmosClientOptions
  {
      ConnectionMode = ConnectionMode.Gateway // ConnectionMode.Direct is the default
  }
);

Geçici port tükenmesi

Örneklerinizde yüksek bağlantı hacmi veya yüksek bağlantı noktası kullanımı görürseniz, önce istemci örneklerinizin tekil olduğunu doğrulayın. Başka bir deyişle, istemci örnekleri uygulamanın ömrü boyunca benzersiz olmalıdır.

TCP protokolünde çalışırken istemci, uzun süreli bağlantıları kullanarak gecikme süresi için iyileştirmeler gerçekleştirir. Bu, iki dakika etkinlik dışı kalma süresinden sonra bağlantıları sonlandıran HTTPS protokolünün aksinedir.

Seyrek erişime sahip olduğunuz senaryolarda ve Ağ Geçidi modu erişimine kıyasla daha yüksek bir bağlantı sayısı fark ederseniz şunları yapabilirsiniz:

  • CosmosClientOptions.PortReuseMode özelliğini olarak PrivatePortPool yapılandırın (çerçeve sürümleri 4.6.1 ve üzeri ve .NET Core sürüm 2.0 ve üzeri ile etkindir). Bu özellik, SDK'nın çeşitli Azure Cosmos DB hedef uç noktaları için kısa ömürlü bağlantı noktalarının küçük bir havuzunu kullanmasına olanak tanır.
  • CosmosClientOptions.IdleTcpConnectionTimeout özelliğini 10 dakikadan büyük veya buna eşit olarak yapılandırın. Önerilen değerler 20 dakika ile 24 saat arasındadır.

Performans için istemcileri aynı Azure bölgesinde birlikte yerleştirin

Mümkün olduğunda, Azure Cosmos DB'yi çağıran tüm uygulamaları Azure Cosmos DB veritabanıyla aynı bölgeye yerleştirin. Yaklaşık bir karşılaştırma: Aynı bölge içindeki Azure Cosmos DB çağrıları 1 milisaniye (ms) ile 2 ms arasında tamamlanır, ancak ABD'nin Batı ve Doğu kıyısı arasındaki gecikme süresi 50 ms'den fazladır. Bu gecikme süresi, istemciden Azure veri merkezi sınırına geçerken istek tarafından alınan yola bağlı olarak istekten isteğe farklılık gösterebilir.

Çağrı yapan uygulamanın sağlanan Azure Cosmos DB uç noktasıyla aynı Azure bölgesinde bulunduğundan emin olarak mümkün olan en düşük gecikme süresini alabilirsiniz. Kullanılabilir bölgelerin listesi için bkz . Azure bölgeleri.

Aynı bölgedeki birlikte bulunan istemcileri gösteren diyagram.

İş parçacığı/görev sayısını artırma

Azure Cosmos DB'ye yapılan çağrılar ağ üzerinden yapıldığından, istemci uygulamasının istekler arasında beklemeye en az zaman harcaması için isteklerinizin eşzamanlılık derecesini değiştirmeniz gerekebilir. Örneğin, .NET Görev Paralel Kitaplığı'nı kullanıyorsanız, Azure Cosmos DB'den okunan veya Azure Cosmos DB'ye yazılan yüzlerce görev sırasına göre oluşturun.

Gecikme süresini ve CPU değişimlerini azaltmak için hızlandırılmış ağı etkinleştirme

Performansı en üst düzeye çıkarmak için Windows veya Linux Azure VM'nizdeHızlandırılmış Ağ'ı etkinleştirmek için yönergeleri izlemeniz önerilir.

Hızlandırılmış ağ olmadan, Azure VM'niz ile diğer Azure kaynakları arasında geçiş yapan Giriş/Çıkış, VM ile ağ kartı arasında yer alan bir konak ve sanal anahtar üzerinden gereksiz yere yönlendirilebilir. Ana bilgisayar ve sanal anahtarın veri yolu boyunca aynı anda bulunması, yalnızca iletişim kanalındaki gecikmeyi ve zaman aralığı dalgalanmasını artırmakla kalmaz, aynı zamanda VM'den CPU döngülerini de çalar. Hızlandırılmış ağ ile VM, aracı olmadan doğrudan NIC ile arabirim oluşturur; Konak ve sanal anahtar tarafından işlenen tüm ağ ilkesi ayrıntıları artık NIC'deki donanımda işlenir; konak ve sanal anahtar atlanır. Genellikle daha düşük gecikme süresi ve daha yüksek aktarım hızının yanı sıra hızlandırılmış ağı etkinleştirdiğinizde daha tutarlı gecikme süresi ve daha az CPU kullanımı bekleyebilirsiniz.

Sınırlamalar: Hızlandırılmış ağ VM işletim sisteminde desteklenmeli ve yalnızca VM durdurulduğunda ve serbest bırakıldığında etkinleştirilebilir. VM, Azure Resource Manager ile dağıtılamaz. App Service'de hızlandırılmış ağ etkinleştirilmedi.

Diğer ayrıntılar için Bkz. Windows ve Linux yönergeleri.

SDK kullanımı

En son SDK'sını yükleme

Azure Cosmos DB SDK'ları en iyi performansı sağlayacak şekilde sürekli geliştirilmektedir. En son SDK'yı belirlemek ve iyileştirmeleri gözden geçirmek için bkz . Azure Cosmos DB SDK'sı.

Akış API'lerini kullanma

.NET SDK V3 , seri hale getirmeden veri alabilen ve döndürebilen akış API'leri içerir.

Doğrudan SDK'dan gelen yanıtları kullanmayan ancak bunları diğer uygulama katmanlarına aktaran orta katman uygulamalar, akış API'lerinden yararlanabilir. Akış işleme örnekleri için bkz . öğe yönetimi örnekleri.

Uygulamanızın ömrü boyunca tek bir Azure Cosmos DB istemcisi kullanma

Her CosmosClient örnek iş parçacığı açısından güvenlidir ve doğrudan modda çalıştığında verimli bağlantı yönetimi ve adres önbelleğe alma işlemi gerçekleştirir. Verimli bağlantı yönetimine ve daha iyi SDK istemci performansına izin vermek için, uygulamanızın etkileşimde bulunduğu her hesap için uygulamanın kullanım ömrü boyunca tek AppDomain bir örnek kullanmanızı öneririz.

Birden çok hesabı işleyen çok kiracılı uygulamalar için ilgili en iyi yöntemlere bakın.

Azure İşlevleri üzerinde çalışırken örneklerin de mevcut yönergeleri izlemesi ve tek bir örneği koruması gerekir.

Aramaları engellemekten kaçının

Azure Cosmos DB SDK'sı, birçok isteği aynı anda işlenecek şekilde tasarlanmalıdır. Asenkron API'ler, bloklama çağrılarını beklemeyerek küçük bir iş parçacığı havuzunun binlerce eşzamanlı isteği işlemesine olanak sağlar. İş parçacığı, uzun süre çalışan bir eşzamanlı görevin tamamlanmasını beklemek yerine başka bir isteğe çalışabilir.

Azure Cosmos DB SDK'sını kullanan uygulamalarda sık karşılaşılan bir performans sorunu, zaman uyumsuz olabilecek çağrıları engelliyor. Birçok senkron engelleyici çağrı, iş parçacığı havuzu tıkanıklığına ve yanıt sürelerinin bozulmasına neden oluyor.

Aşağıdakileri yapma:

  • Task.Wait veya Task.Result çağrısı yaparak zaman uyumsuz yürütmeyi engelleyin.
  • Zaman uyumlu API'yi zaman uyumsuz yapmak için Task.Run kullanın.
  • Ortak kod yollarında kilitleri al. Azure Cosmos DB .NET SDK'sı, kod paralel olarak çalıştırılacak şekilde tasarlandığında en yüksek performansı gösterir.
  • Task.Run'ı çağırıp hemen beklemeye devam edin. ASP.NET Core, uygulama kodunu normal İş Parçacığı Havuzu iş parçacıklarında zaten çalıştırdığından Task.Run çağrısı yalnızca gereksiz iş parçacığı havuzu zamanlaması sağlar. Zamanlanan kod bir iş parçacığını engellese bile Task.Run bunu engellemez.
  • ToList() Container.GetItemLinqQueryable<T>() kullanmayın, çünkü sorguyu senkron olarak boşaltmak için engelleme çağrılarını kullanır. Sorguyu zaman uyumsuz olarak boşaltmak için ToFeedIterator() kullanın.

Yap:

  • Azure Cosmos DB .NET API'lerini zaman uyumsuz olarak çağırın.
  • Tüm çağrı yığını async/await desenlerinden yararlanmak için eşzamanlı çalışır.

PerfView gibi bir profil oluşturucu, iş parçacığı havuzuna sık sık eklenen iş parçacıklarını bulmak için kullanılabilir. Microsoft-Windows-DotNETRuntime/ThreadPoolWorkerThread/Start olayı, iş parçacığı havuzuna eklenen bir iş parçacığını belirtir.

Yazma işlemlerinde içerik yanıtlarını devre dışı bırakma

Oluşturma yükleri fazla olan iş yükleri için EnableContentResponseOnWrite istek seçeneğini false olarak ayarlayın. Hizmet artık oluşturulan veya güncelleştirilmiş kaynağı SDK'ya döndürmez. Normalde, uygulama oluşturulan nesneye sahip olduğundan, hizmetin nesneyi geri döndürmesine gerek yoktur. Başlık değerleri, istek ücreti gibi bilgilere hâlâ erişilebilir. İçerik yanıtını devre dışı bırakmak, SDK'nın artık bellek ayırmak veya yanıtın gövdesini seri hale getirmek zorunda kalmaması anlamına geleceği için performansın geliştirilmesine yardımcı olabilir. Ayrıca performansa daha fazla yardımcı olmak için ağ bant genişliği kullanımını azaltır.

ItemRequestOptions requestOptions = new ItemRequestOptions() { EnableContentResponseOnWrite = false };
ItemResponse<Book> itemResponse = await this.container.CreateItemAsync<Book>(book, new PartitionKey(book.pk), requestOptions);
// Resource will be null
itemResponse.Resource

Gecikme yerine aktarım hızını iyileştirmek için Toplu'yu etkinleştir

İş yükünün büyük miktarda aktarım hızı gerektirdiği ve gecikme süresinin o kadar önemli olmadığı senaryolar için Toplu modunu etkinleştirin. Toplu özelliğini etkinleştirme hakkında daha fazla bilgi edinmek ve hangi senaryolar için kullanılması gerektiğini öğrenmek için bkz Toplu Desteğe Giriş.

Gateway modunu kullanırken her ana bilgisayar için System.Net Maksimum Bağlantılar artırma

Azure Cosmos DB istekleri, Ağ Geçidi modunu kullandığınızda HTTPS/REST üzerinden yapılır. Ana bilgisayar adı veya IP adresi başına varsayılan bağlantı sınırına tabidir. İstemci kitaplığının Azure Cosmos DB'ye birden çok eşzamanlı bağlantı kullanabilmesi için daha yüksek bir değere (100 ile 1.000 arasında) ayarlamanız MaxConnections gerekebilir. .NET SDK 1.8.0 ve sonraki sürümlerinde, ServicePointManager.DefaultConnectionLimit için varsayılan değer 50'dir. Değeri değiştirmek için daha yüksek bir değere ayarlayabilirsiniz Documents.Client.ConnectionPolicy.MaxConnectionLimit .

İş parçacığı/görev sayısını artırma

Bu makalenin Ağ oluşturma bölümünde bulunan İş parçacığı/görev sayısını artırma kısmına bakın.

Newtonsoft.Json Bağımlılıklarını Yönetme

Overview

Azure Cosmos DB .NET SDK'sının JSON serileştirme işlemlerine bağımlılığı Newtonsoft.Json vardır. Bu bağımlılık otomatik olarak yönetilmiyor ; projenize doğrudan bağımlılık olarak açıkça eklemeniz Newtonsoft.Json gerekir.

SDK, bilinen bir güvenlik açığı olan Newtonsoft.Json 10.x'e karşı dahili olarak derler. SDK teknik olarak 10.x ile uyumludur ve SDK'nın Newtonsoft.Json kullanımı bildirilen güvenlik sorununa açık olmasa da, olası güvenlik sorunlarını veya çakışmalarını önlemek için 13.0.3 veya üzeri bir sürümü kullanmanızı öneririz . 13.x sürümleri hataya neden olan değişiklikleri içerir, ancak SDK'nın kullanım desenleri bu değişikliklerle uyumludur.

Important

Bu bağımlılıkSystem.Text.Json aracılığıyla kullanıcı tanımlı türler için kullanılırken bile gereklidir çünkü SDK'nın iç işlemleri sistem türleri için hala Newtonsoft.Json kullanır.

Azure Cosmos DB .NET SDK v3 kullanırken her zaman doğrudan bağımlılık olarak 13.0.3 veya üzeri bir sürümü açıkça ekleyinNewtonsoft.Json. Bilinen güvenlik açıklarından dolayı 10.x sürümünü kullanmayın.

Standart .csproj Projeleri için

<ItemGroup>
  <PackageReference Include="Microsoft.Azure.Cosmos" Version="3.47.0" />
  <PackageReference Include="Newtonsoft.Json" Version="13.0.4" />
</ItemGroup>

Merkezi Paket Yönetimi Kullanan Projeler için

Projeniz kullanıyorsa Directory.Packages.props:

<Project>
  <ItemGroup>
    <PackageVersion Include="Microsoft.Azure.Cosmos" Version="3.47.0" />
    <PackageVersion Include="Newtonsoft.Json" Version="13.0.4" />
  </ItemGroup>
</Project>

Sürüm Çakışmaları Sorunlarını Giderme

Eksik Newtonsoft.Json Referansı

Şöyle bir derleme hatasıyla karşılaşırsanız:

The Newtonsoft.Json package must be explicitly referenced with version >= 10.0.2. Please add a reference to Newtonsoft.Json or set the 'AzureCosmosDisableNewtonsoftJsonCheck' property to 'true' to bypass this check.

Bu hata, bağımlılığın düzgün yapılandırıldığından emin olmak için Cosmos DB SDK'sının derleme hedefleri tarafından kasıtlı olarak oluşturulur.

Uygulamalar için Çözüm:

Yukarıdaki Önerilen Yapılandırma bölümünde gösterildiği gibi Newtonsoft.Json dosyasına açık bir başvuru ekleyin.

Kitaplıklar için çözüm:

Bir kitaplık oluşturuyorsanız (uygulama değil) ve Newtonsoft.Json bağımlılığını kitaplığınızın tüketicilerine ertelemek istiyorsanız, içinde MSBuild özelliğini ayarlayarak bu denetimi atlayabilirsiniz .csproj:

<PropertyGroup>
  <AzureCosmosDisableNewtonsoftJsonCheck>true</AzureCosmosDisableNewtonsoftJsonCheck>
</PropertyGroup>

Warning

Bu atlama yalnızca son kullanıcıların Newtonsoft.Json bağımlılığını sağlayacağı kitaplıklar oluştururken kullanın. Uygulamalar için her zaman belirgin referansı ekleyin.

Paket Sürümü Çakışmaları

Şu gibi derleme hatalarıyla karşılaşırsanız:

error NU1109: Detected package downgrade: Newtonsoft.Json from 13.0.4 to centrally defined 13.0.3

Çözüm:

  1. Hangi paketlerin daha yeni sürümlere ihtiyacı olduğunu denetleyerek gerekli sürümü belirleyin:

    dotnet list package --include-transitive | Select-String "Newtonsoft.Json"

  2. Merkezi paket sürümünüzü gerekli en yüksek sürümle eşleşecek veya bu sürümü aşacak şekilde güncelleştirin:

    <PackageVersion Include="Newtonsoft.Json" Version="13.0.4" />

  3. Temizleme ve yeniden oluşturma:

    dotnet clean
dotnet restore
dotnet build

Sürüm Uyumluluğu

Aşağıdaki tabloda, her Cosmos DB SDK sürümü için önerilen en düşük güvenli Newtonsoft.Json sürümleri gösterilmektedir. SDK teknik olarak 10.x ile çalışasa da, bu sürümler güvenlik açıkları nedeniyle hiçbir zaman kullanılmamalıdır.

Cosmos DB SDK Sürümü En Düşük Güvenli Sürüm Recommended
3.47.0+ 13.0.3 13.0.4
3.54.0+ 13.0.4 13.0.4

Tip

.NET Aspire 13.0.0 veya üzerini kullanırken Aspire'in Azure bileşenleriyle çakışmaları önlemek için sürüm 13.0.4'te olduğundan emin olun Newtonsoft.Json .

En İyi Uygulamalar

  • Her zaman doğrudan bağımlılık olarak ekle - SDK bu bağımlılığı sizin için otomatik olarak yönetmez
  • Sürüm 13.0.3 veya üzerini kullanma - Bilinen güvenlik açıkları nedeniyle teknik uyumluluğa rağmen asla 10.x kullanmayın
  • System.Text.Json ile bile gereklidir - SDK sistem türleri için dahili olarak kullandığından, kullanırken bile UseSystemTextJsonSerializerWithOptionsNewtonsoft.Json eklemeniz gerekir.
  • Sürümü açıkça sabitleyin - Geçişli bağımlılık çözümlemesine güvenmeyin
  • Uyarıları izleme - NuGet paketi sürüm düşürme uyarılarını (NU1109) CI/CD işlem hatlarında hata olarak değerlendirin

Sorgu işlemleri

Sorgu işlemleri için bkz. Sorgular için performans ipuçları.

Dizin oluşturma ilkesi

Daha hızlı yazma işlemleri için, kullanılmayan yolları dizin oluşturmanın dışında bırakma

Azure Cosmos DB dizin oluşturma ilkesi, dizin oluşturma yollarını (IndexingPolicy.IncludedPaths ve IndexingPolicy.ExcludedPaths) kullanarak hangi belge yollarının dizine ekleneceğini veya dizin oluşturmanın dışında tutulacağını belirtmenize de olanak tanır.

Yalnızca ihtiyacınız olan yolları dizine eklemek yazma performansını artırabilir, yazma işlemlerinde RU ücretlerini azaltabilir ve sorgu desenlerinin önceden bilindiği senaryolar için dizin depolama alanını azaltabilir. Bunun nedeni, dizin oluşturma maliyetlerinin doğrudan dizine alınan benzersiz yol sayısıyla bağıntılı olmasıdır. Örneğin, aşağıdaki kod, * joker karakterini kullanarak belgelerin bir bölümünün (alt ağaç) dizinlemeye dahil edilmemesini gösterir.

var containerProperties = new ContainerProperties(id: "excludedPathCollection", partitionKeyPath: "/pk" );
containerProperties.IndexingPolicy.IncludedPaths.Add(new IncludedPath { Path = "/*" });
containerProperties.IndexingPolicy.ExcludedPaths.Add(new ExcludedPath { Path = "/nonIndexedContent/*");
Container container = await this.cosmosDatabase.CreateContainerAsync(containerProperties);

Daha fazla bilgi için bkz . Azure Cosmos DB dizin oluşturma ilkeleri.

Verimlilik

Daha düşük RU/sn kullanımı için ölçme ve ayarlama

Azure Cosmos DB zengin bir veritabanı işlemleri kümesi sunar. Bu işlemler kullanıcı tanımlı işlevler (UDF' ler), saklı yordamlar ve tetikleyiciler içeren ilişkisel ve hiyerarşik sorguları içerir ve bunların tümü bir veritabanı koleksiyonundaki belgeler üzerinde çalışır.

Bu işlemlerin her biriyle ilişkili maliyetler, işlemi tamamlamak için gereken CPU, GÇ ve belleğe bağlı olarak değişir. Donanım kaynaklarını düşünmek ve yönetmek yerine, bir İstek Birimi'ni çeşitli veritabanı işlemlerini gerçekleştirmek ve bir uygulama isteğine hizmet vermek için gereken kaynaklar için tek bir ölçü olarak düşünebilirsiniz.

Aktarım hızı, her kapsayıcı için ayarlanan İstek Birimi sayısına göre sağlanır. RU tüketimi saniye başına birim hızı olarak değerlendirilir. Kapsayıcıları için sağlanan RU oranını aşan uygulamalar, hız kapsayıcı için sağlanan düzeyin altına düşene kadar sınırlıdır. Uygulamanız daha yüksek aktarım hızı düzeyi gerektiriyorsa daha fazla RU sağlayarak aktarım hızınızı artırabilirsiniz.

Sorgunun karmaşıklığı, işlem için tüketilen RU sayısını etkiler. Koşulların sayısı, koşulların yapısı, UDF dosyalarının sayısı ve kaynak veri kümesinin boyutu sorgu işlemlerinin maliyetini etkiler.

Herhangi bir işlemin (oluşturma, güncelleştirme veya silme) ek yükünü ölçmek için x-ms-request-charge üst bilgisini (veya .NET SDK'sında veya RequestCharge .NET SDK'sında ResourceResponse<T> eşdeğer FeedResponse<T> özelliği) inceleyerek işlemler tarafından kullanılan RU sayısını ölçün:

// Measure the performance (Request Units) of writes
ItemResponse<Book> response = await container.CreateItemAsync<Book>(myBook, new PartitionKey(myBook.PkValue));
Console.WriteLine("Insert of item consumed {0} request units", response.RequestCharge);
// Measure the performance (Request Units) of queries
FeedIterator<Book> queryable = container.GetItemQueryIterator<ToDoActivity>(queryString);
while (queryable.HasMoreResults)
    {
        FeedResponse<Book> queryResponse = await queryable.ExecuteNextAsync<Book>();
        Console.WriteLine("Query batch consumed {0} request units", queryResponse.RequestCharge);
    }

Bu üst bilgide döndürülen istek ücreti, sağlanan aktarım hızınızın (yani 2.000 RU/sn) bir bölümüdür. Örneğin, önceki sorgu 1.000 1 KB belge döndürürse, işlemin maliyeti 1.000'dir. Bu nedenle, sunucu bir saniye içinde, daha sonraki istekleri sınırlamadan önce bu tür iki isteği kabul eder. Daha fazla bilgi için bkz . İstek Birimleri ve İstek Birimi hesaplayıcısı.

Hız sınırlamasını yönet/istek hızı çok yüksek

İstemci bir hesap için ayrılmış aktarım hızını aşmaya çalıştığında, sunucuda performans düşüşü olmaz ve ayrılmış düzeyin ötesinde aktarım hızı kapasitesi kullanılamaz. Sunucu isteği requestRateTooLarge (HTTP durum kodu 429) ile önceden sona erdirir. Kullanıcının isteği yeniden denemeden önce beklemesi gereken süreyi milisaniye cinsinden belirten bir x-ms-retry-after-ms üst bilgisi döndürür.

    HTTP Status 429,
    Status Line: RequestRateTooLarge
    x-ms-retry-after-ms :100

SDK'ların tümü bu yanıtı örtük olarak yakalar, sunucuda belirtilen retry-after üst bilgisine saygı gösterir ve isteği yeniden dener. Hesabınıza birden çok istemci tarafından eşzamanlı olarak erişilmediği sürece sonraki yeniden deneme başarılı olur.

İstek oranının üzerinde tutarlı bir şekilde çalışan birden fazla istemciniz varsa, şu anda istemci tarafından dahili olarak 9 olarak ayarlanmış olan varsayılan yeniden deneme sayısı yeterli olmayabilir. Bu durumda istemci, uygulamaya durum kodu 429 olan bir CosmosException oluşturur.

Varsayılan yeniden deneme sayısını, RetryOptions örneğindeki CosmosClientOptions ayarını yaparak değiştirebilirsiniz. Varsayılan olarak, istek istek hızının üzerinde çalışmaya devam ederse 30 saniyelik bir kümülatif bekleme süresinden sonra durum kodu 429 olan CosmosException döndürülür. Geçerli yeniden deneme sayısı, varsayılan değer olan 9 veya kullanıcı tanımlı bir değer olsa bile, maksimum yeniden deneme sayısından az olduğunda bu hata döndürülür.

Otomatik yeniden deneme davranışı, çoğu uygulama için dayanıklılığı ve kullanılabilirliği geliştirmeye yardımcı olur. Ancak bu, özellikle gecikme süresini ölçerken performans karşılaştırmaları yaparken en iyi davranış olmayabilir. Deneme sunucu kısıtlamasına isabet ederse ve istemci SDK'sının sessizce yeniden denemesine neden olursa istemci tarafından gözlemlenen gecikme süresi artar. Performans testleri sırasında gecikme süresi artışlarını önlemek için her işlemde dönen yükü ölçün ve isteklerin belirlenmiş istek oranının altında çalıştığından emin olun.

Daha fazla bilgi için bkz İstek Birimleri.

Daha yüksek aktarım hızı için, daha küçük belgeler için tasarım

Belirtilen işlemin istek ücreti (yani istek işleme maliyeti), doğrudan belgenin boyutuyla ilişkilendirilir. Büyük belgelerdeki işlemler, küçük belgelerdeki işlemlerden daha pahalıdır.

Sonraki Adımlar

  • Last updated on