Azure Cosmos DB Python SDK'sı için performans ipuçları

• Python SDK'sı
• Java SDK v4
• Async Java SDK v2
• Java SDK v2'yi eşitleme
• .NET SDK v3
• .NET SDK v2

Önemli

Bu makaledeki performans ipuçları yalnızca Azure Cosmos DB Python SDK'sı içindir. Daha fazla bilgi için lütfen Azure Cosmos DB Python SDK Readme, Sürüm notları, Paket (PyPI), Paket (Conda) ve sorun giderme kılavuzuna bakın.

Azure Cosmos DB, garantili gecikme süresi ve aktarım hızı ile sorunsuz bir şekilde ölçeklendirilen hızlı ve 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çeklendirmeyi artırmak veya azaltmak, tek bir API çağrısı veya SDK yöntem çağrısı yapmak kadar kolaydır. Ancak Azure Cosmos DB'ye ağ çağrıları aracılığıyla erişildiğinden, Azure Cosmos DB Python SDK'sını kullanırken en yüksek performansı elde etmek için istemci tarafı iyileştirmeleri yapabilirsiniz.

Bu nedenle "Veritabanımın performansını nasıl geliştirebilirim?" sorusunu soruyorsanız aşağıdaki seçenekleri göz önünde bulundurun:

Ağ Kurma

• Performans için aynı Azure bölgesindeki istemcileri birlikte dağıtma

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 için, aynı bölge içindeki Azure Cosmos DB çağrıları 1-2 ms içinde tamamlanır, ancak ABD'nin Batı ve Doğu kıyısı arasındaki gecikme süresi 50 ms'dir >. Bu gecikme süresi, istemciden Azure veri merkezi sınırına geçerken talebin izlediği güzergaha bağlı olarak bir talepten diğerine 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 olunarak mümkün olan en düşük gecikme süresi elde edilir. Kullanılabilir bölgelerin listesi için bkz . Azure Bölgeleri.

Çok bölgeli bir Azure Cosmos DB hesabıyla etkileşim kuran bir uygulamanın, isteklerin birlikte bulunan bir bölgeye gidildiğinden emin olmak için tercih edilen konumları yapılandırması gerekir.

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

Performansı en üst düzeye çıkarmak (gecikme süresini ve CPU değişimini azaltmak) için Windows'unuzda Hızlandırılmış Ağ'ı (yönergeler için seçin) veya Linux'u (yönergeler için seçin) Azure VM'nizde 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.

Daha fazla ayrıntı için lütfen Windows ve Linux yönergelerine bakın.

Yüksek ulaşı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, bölüm düzeyi devre kesici Python SDK'sında uygulanabilir ve bu da kesinti senaryolarında yardımcı olabilir. Bu özellik, varsayılan olarak SDK'da yerleşik olarak bulunan bölgeler arası yeniden deneme özelliklerinin üstünde ve ötesinde gelişmiş mekanizma kullanılabilirliği zorlukları sağlar. Bu, özellikle yüksek yük veya düzeyi düşürülmüş koşullar altında uygulamanızın dayanıklılığını ve performansını önemli ölçüde artırabilir.

Bölüm düzeyi devre kesici

Python SDK'sında bölüm düzeyi devre kesici (PPCB), tek tek fiziksel bölümlerin durumunu ve yönlendirme isteklerini sorunlu bölümlerden uzağa izleyerek kullanılabilirliği ve dayanıklılığı geliştirir. Bu özellik özellikle ağ sorunları, bölüm yükseltmeleri veya geçişler gibi geçici ve terminal sorunlarını işlemek için kullanışlıdır.

PPCB aşağıdaki senaryolarda geçerlidir:

• Herhangi bir tutarlılık düzeyi
• Bölüm anahtarıyla işlemler (nokta okuma/yazma işlemleri)
• Tek yazma bölgesine sahip hesaplar ve birden çok okuma bölgesi
• Birden fazla yazma bölge hesabı

Nasıl çalışır?

Bölümler, isteklerin başarılı veya başarısız olmasına göre dört durumdan geçer: Sağlıklı, Sağlıksız Belirsiz, Sağlıksız, ve Sağlıklı Belirsiz.

1. Hata İzleme: SDK, bölüm başına hata oranlarını (örneğin, 5xx, 408) bir dakikalık bir süre boyunca izler. Bölüm başına ardışık hatalar SDK tarafından süresiz olarak izlenir.
2. Kullanılamıyor Olarak İşaretleme: Bir bölüm yapılandırılmış eşikleri aşarsa, İyi Durumda Olmayan Belirsiz olarak işaretlenir ve 1 dakika boyunca yönlendirmenin dışında tutulur.
3. Sağlıksız Duruma veya Kurtarma Durumuna Yükseltme: Kurtarma girişimleri başarısız olursa bölüm Sağlıksız Duruma geçiş yapar. Geri çekilme aralığından sonra, kurtarmayı belirlemek için süre sınırı olan bir istekle Sağlıklı Deneme kontrolü yapılır.
4. Yeniden devreye alma: Geçici yoklama başarılı olursa, bölüm Sağlıklı durumuna döner. Aksi takdirde, sonraki yoklama kadar sağlıksız kalır.

Bu yük devretme SDK tarafından dahili olarak yönetilir ve isteklerin bilinen sorunlu bölümlerden tekrar iyi durumda olduğu onaylanana kadar kaçınmasını sağlar.

Ortam değişkenleri aracılığıyla yapılandırma

Şu ortam değişkenlerini kullanarak PPCB davranışını denetleyebilirsiniz:

Variable	Description	Varsayılan
AZURE_COSMOS_ENABLE_CIRCUIT_BREAKER	PPCB'yi etkinleştirir/devre dışı bırakır	false
AZURE_COSMOS_CONSECUTIVE_ERROR_COUNT_TOLERATED_FOR_READ	Bir bölümü kullanılamaz olarak işaretlemeden önce ardışık okuma hatalarının en fazla sayısı	10
AZURE_COSMOS_CONSECUTIVE_ERROR_COUNT_TOLERATED_FOR_WRITE	Bir bölümü kullanılamaz olarak işaretlemeden önce en fazla art arda yazma hatası	5
AZURE_COSMOS_FAILURE_PERCENTAGE_TOLERATED	Bir bölümü kullanılamaz olarak işaretlemeden önce hata yüzdesi eşiği	90

Tavsiye

Ek yapılandırma seçenekleri, zaman aşımı sürelerinde ince ayar yapmak ve kurtarma geri alma davranışı için gelecek sürümlerde kullanıma sunılabilir.

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 Python SDK'sı sürüm 4.14.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 hem istemci düzeyinde hem de istek düzeyinde yapılandırılabilir:

from azure.cosmos import CosmosClient
from azure.cosmos.partition_key import PartitionKey

# Configure preferred locations and excluded locations at client level

preferred_locations = ['West US 3', 'West US', 'East US 2']
excluded_locations_on_client = ['West US 3', 'West US']

client = CosmosClient(
    url=HOST,
    credential=MASTER_KEY,
    preferred_locations=preferred_locations,
    excluded_locations=excluded_locations_on_client
)

database = client.create_database('TestDB')
container = database.create_container(
    id='TestContainer',
    partition_key=PartitionKey(path="/pk")
)

# Create an item (writes ignore excluded_locations in single-region write accounts)
test_item = {
    'id': 'Item_1',
    'pk': 'PartitionKey_1',
    'test_object': True,
    'lastName': 'Smith'
}
created_item = container.create_item(test_item)

# Read operations will use preferred_locations minus excluded_locations
# In this example: ['West US 3', 'West US', 'East US 2'] - ['West US 3', 'West US'] = ['East US 2']
item = container.read_item(
    item=created_item['id'],
    partition_key=created_item['pk']
)

İstek düzeyinde dışlanan bölgeler:

İstek düzeyi dışlanan bölgeler en yüksek önceliğe sahiptir ve istemci düzeyi ayarlarını geçersiz kılar:

# Excluded locations can be specified per request, overriding client settings
excluded_locations_on_request = ['West US 3']

# Create item with request-level excluded regions
created_item = container.create_item(
    test_item,
    excluded_locations=excluded_locations_on_request
)

# Read with request-level excluded regions
# This will use: ['West US 3', 'West US', 'East US 2'] - ['West US 3'] = ['West US', 'East US 2']
item = container.read_item(
    item=created_item['id'],
    partition_key=created_item['pk'],
    excluded_locations=excluded_locations_on_request
)

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.

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 Azure Cosmos DB SDK sürüm notlarına bakın.

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

Her Azure Cosmos DB istemci örneği iş parçacığı açısından güvenlidir ve verimli bağlantı yönetimi ve adres önbelleği gerçekleştirir. Azure Cosmos DB istemcisi tarafından verimli bağlantı yönetimine ve daha iyi performansa izin vermek için uygulamanın ömrü boyunca Azure Cosmos DB istemcisinin tek bir örneğinin kullanılması önerilir.

• Zaman aşımını ayarlama ve yapılandırmaları yeniden deneme

Zaman aşımı yapılandırmaları ve yeniden deneme ilkeleri, uygulama gereksinimlerine göre özelleştirilebilir. Zaman aşımı ve yeniden deneme yapılandırması belgesine başvurarak özelleştirilebilen yapılandırmaların tam listesini edinin.

• Uygulamanız için gereken en düşük tutarlılık düzeyini kullanın

CosmosClient oluşturduğunuzda, istemci oluşturma işleminde belirtilmemişse hesap düzeyi tutarlılığı kullanılır. Tutarlılık düzeyleri hakkında daha fazla bilgi için tutarlılık düzeyleri belgesine bakın.

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

Yüksek aktarım hızı düzeylerinde test ediyorsanız, makinenin CPU veya ağ kullanımının sınırlarını zorlaması nedeniyle istemci uygulaması darboğaz haline gelebilir. Bu noktaya ulaşırsanız, istemci uygulamalarınızı birden çok sunucuya yayarak Azure Cosmos DB hesabınızı daha da genişletebilirsiniz.

Gecikme süresini düşük tutmak için belirli bir sunucuda %50 CPU kullanımını aşmamak >iyi bir kuraldır.

• OS Açık Dosya Kaynak Limiti

Bazı Linux sistemleri (Red Hat gibi) açık dosya sayısı ve dolayısıyla toplam bağlantı sayısı üzerinde üst sınıra sahiptir. Geçerli sınırları görüntülemek için aşağıdakileri çalıştırın:

ulimit -a

Açık dosyaların (nofile) sayısının, yapılandırılmış bağlantı havuzu boyutunuz ve işletim sistemi tarafından diğer açık dosyalar için yeterli alan olacak kadar büyük olması gerekir. Daha büyük bir bağlantı havuzu boyutuna izin verecek şekilde değiştirilebilir.

limits.conf dosyasını açın:

vim /etc/security/limits.conf

Aşağıdaki satırları ekleyin/değiştirin:

* - nofile 100000

Sorgu işlemleri

Sorgu işlemleri için sorgular için performans ipuçlarına bakın.

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'nin dizin oluşturma ilkesi, Dizin Oluşturma Yolları'ndan (setIncludedPaths ve setExcludedPaths) yararlanarak hangi belge yollarının dizine ekleneceğini veya dizin oluşturmanın dışında tutulacağını belirtmenize olanak tanır. Dizin oluşturma maliyetlerinin dizine alınan benzersiz yol sayısıyla doğrudan bağıntılı olması nedeniyle, dizin oluşturma yollarının kullanımı, sorgu desenlerinin önceden bilindiği senaryolar için gelişmiş yazma performansı ve daha düşük dizin depolaması sunabilir. Örneğin, aşağıdaki kodda belgelerin tüm bölümlerinin (alt ağaç olarak da bilinir) "*" joker karakteri kullanılarak dizin oluşturma işleminin nasıl dahil edilip dışlandığı gösterilmektedir.

container_id = "excluded_path_container"
indexing_policy = {
        "includedPaths" : [ {'path' : "/*"} ],
        "excludedPaths" : [ {'path' : "/non_indexed_content/*"} ]
        }
db.create_container(
    id=container_id,
    indexing_policy=indexing_policy,
    partition_key=PartitionKey(path="/pk"))

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

Throughput

• Daha düşük istek birimleri/saniye kullanımı için ölçme ve ayarlama

Azure Cosmos DB, UDF'ler, saklı yordamlar ve tetikleyiciler içeren ilişkisel ve hiyerarşik sorgular da dahil olmak üzere zengin bir veritabanı işlemleri kümesi sunar. Bunların tümü bir veritabanı koleksiyonundaki belgeler üzerinde çalışır. Bu işlemlerden her biriyle ilişkilendirilmiş maliyet, işlemi tamamlamak için gereken CPU, GÇ ve belleğe göre değişiklik gösterir. Donanım kaynaklarını düşünmek ve yönetmek yerine, bir istek birimini (RU) ç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 istek birimi sayısına göre sağlanır. İstek birimi tüketimi saniye başına hız olarak değerlendirilir. Kapsayıcıları için sağlanan istek birimi hızı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 bir aktarım hızı düzeyi gerektiriyorsa, ek istek birimleri sağlayarak aktarım hızınızı artırabilirsiniz.

Sorgunun karmaşıklığı, bir işlem için kaç istek biriminin tüketilmiş olduğunu etkiler. Koşul sayısı, koşulların yapısı, UDF sayısı ve kaynak veri kümesinin boyutu, sorgu işlemlerinin maliyetini etkiler.

Herhangi bir işlemin yükünü ölçmek için (oluşturma, güncelleştirme veya silme), x-ms-request-charge üst bilgisini inceleyerek bu işlemler tarafından kullanılan istek birimi sayısını ölçün.

document_definition = {
    'id': 'document',
    'key': 'value',
    'pk': 'pk'
}
document = container.create_item(
    body=document_definition,
)
print("Request charge is : ", container.client_connection.last_response_headers['x-ms-request-charge'])

Bu başlıkta döndürülen talep ücreti, sağlanan aktarım hızınızın bir bölümüdür. Örneğin, sağlanan 2000 RU/sn'niz varsa ve önceki sorgu 1000 1 KB'lık belge döndürüyorsa işlemin maliyeti 1000'dir. Bu nedenle, sunucu bir saniye içinde yalnızca iki isteği kabul eder ve daha sonraki istekleri hız sınırlandırmasına tabi tutar. Daha fazla bilgi için bkz . İstek birimleri ve istek 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 sonlandıracak ve kullanıcının isteği yeniden başlatmadan önce beklemesi gereken süreyi milisaniye cinsinden belirten x-ms-retry-after-ms üst bilgisini 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 çalışan birden fazla istemciniz varsa, şu anda istemci tarafından dahili olarak 9 olarak ayarlanan varsayılan yeniden deneme sayısı yeterli olmayabilir; bu durumda, istemci uygulamaya durum kodu 429 olan bir CosmosHttpResponseError hatası fırlatır. Varsayılan yeniden deneme sayısı, retry_total yapılandırması istemciye geçilerek değiştirilebilir. Varsayılan olarak, istek istek hızının üzerinde çalışmaya devam ederse 30 saniyelik bir toplu bekleme süresinden sonra durum kodu 429 olan CosmosHttpResponseError döndürülür. Bu durum, geçerli yeniden deneme sayısı varsayılan olarak 9 veya kullanıcı tanımlı bir değer olması durumunda maksimum yeniden deneme sayısı'nın altında olsa bile oluşur.

Otomatik yeniden deneme davranışı çoğu uygulama için dayanıklılığı ve kullanılabilirliği artırmaya yardımcı olsa da, performans değerlendirme testleri sırasında, özellikle de gecikme süresini ölçerken, bazen çelişkilere yol açabilir. 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 denemeleri sırasında gecikme sürelerinde ani artışları önlemek için her işlemin döndürdüğü yükü ölçün ve isteklerin ayrılmış istek oranının altında çalıştığından emin olun. Daha fazla bilgi için İstek birimleri bölümüne bakın.

• Daha yüksek aktarım hızı için daha küçük belgeler tasarlama

Belirli bir işlemin istek ücreti (istek işleme maliyeti), belgenin boyutuyla doğrudan ilişkilendirilir. Büyük belgelerdeki işlemler, küçük belgeler için yapılan işlemlerden daha pahalıdır. İdeal olarak, uygulamanızın ve iş akışlarınızın mimarisini, öğe boyutunuzun yaklaşık 1 KB veya benzer bir düzende veya büyüklükte olması için tasarlar. Gecikmeye duyarlı uygulamalarda büyük öğelerden kaçınılmalıdır. Çok MB'lı belgeler uygulamanızı yavaşlatır.

Sonraki Adımlar

Uygulamanızı ölçeklendirme ve yüksek performans için tasarlama hakkında daha fazla bilgi edinmek için bkz . Azure Cosmos DB'de bölümleme ve ölçeklendirme.

Azure Cosmos DB'ye geçiş için kapasite planlaması yapmaya mı çalışıyorsunuz? Kapasite planlaması için mevcut veritabanı kümeniz hakkındaki bilgileri kullanabilirsiniz.

• Tek bildiğiniz mevcut veritabanı kümenizdeki sanal çekirdek ve sunucu sayısıysa, sanal çekirdekleri veya vCPU'ları kullanarak istek birimlerini tahmin etme hakkında bilgi edinin
• Geçerli veritabanı iş yükünüz için tipik istek oranlarını biliyorsanız Azure Cosmos DB kapasite planlayıcısı kullanarak istek birimlerini tahmin etme hakkında bilgi edinin