Praktik terbaik untuk Azure Cosmos DB .NET SDK

  • Artikel

BERLAKU UNTUK: NoSQL

Artikel ini memandu Anda mempelajari praktik terbaik untuk menggunakan Azure Cosmos DB .NET SDK. Mengikuti praktik ini akan membantu meningkatkan latensi, ketersediaan, dan meningkatkan performa Anda secara keseluruhan.

Tonton video di bawah ini untuk mempelajari selengkapnya tentang menggunakan .NET SDK dari teknisi Azure Cosmos DB!

Daftar periksa

Dicentang Subjek Detail/Tautan
Versi SDK Selalu gunakan versi terbaru Azure Cosmos DB SDK yang tersedia untuk performa optimal.
Klien Tunggal Gunakan instans tunggalCosmosClient selama penggunaan aplikasi Anda untuk performa yang lebih baik.
Wilayah Pastikan untuk menjalankan aplikasi Anda di wilayah Azure yang sama dengan akun Azure Cosmos DB Anda, jika memungkinkan untuk mengurangi latensi. Aktifkan 2-4 wilayah dan tiru akun Anda di beberapa wilayah untuk ketersediaan terbaik. Untuk beban kerja produksi, aktifkan failover yang dikelola layanan. Jika konfigurasi ini tidak ada, akun akan mengalami kehilangan ketersediaan tulis selama penghentian wilayah tulis, karena kegagalan manual tidak akan berhasil karena kurangnya konektivitas wilayah. Untuk mempelajari cara menambahkan beberapa wilayah menggunakan .NET SDK kunjungi di sini
Ketersediaan dan Failover Atur ApplicationPreferredRegions atau ApplicationRegion di v3 SDK, dan PreferredLocations di v2 SDK menggunakan daftar wilayah pilihan. Selama failover, operasi tulis dikirim ke wilayah penulisan saat ini dan semua bacaan dikirim ke wilayah pertama dalam daftar wilayah pilihan Anda. Untuk informasi selengkapnya tentang mekanika failover regional, lihat panduan pemecahan masalah ketersediaan.
CPU Anda mungkin mengalami masalah konektivitas/ketersediaan karena kurangnya sumber daya pada mesin klien Anda. Pantau pemanfaatan CPU Anda pada simpul yang menjalankan klien Azure Cosmos DB dan perluas skala jika penggunaan sangat tinggi.
Hosting Jika memungkinkan, gunakan pemrosesan host Windows 64-bit untuk performa terbaik. Untuk beban kerja produksi sensitif latensi mode langsung, sebaiknya gunakan setidaknya 4-core dan VM memori 8 GB jika memungkinkan.
Mode Konektivitas Gunakan Mode langsung untuk performa terbaik. Untuk petunjuk cara melakukan ini, lihat dokumentasi V3 SDK atau dokumentasi V2 SDK.
Jaringan Jika menggunakan mesin virtual untuk menjalankan aplikasi Anda, aktifkan Jaringan Percepatan di mesin virtual Anda untuk membantu penyempitan karena lalu lintas tinggi dan mengurangi latensi atau jitter CPU. Anda mungkin juga ingin mempertimbangkan untuk menggunakan Mesin Virtual kelas atas di mana penggunaan CPU maksimal di bawah 70%.
Kelelahan port sementara Untuk koneksi yang jarang atau sporadis, kami mengatur IdleConnectionTimeout dan PortReuseMode ke PrivatePortPool. Properti IdleConnectionTimeout membantu mengontrol waktu setelah koneksi yang tidak digunakan ditutup. Ini mengurangi jumlah koneksi yang tidak digunakan. Secara default, koneksi idle tetap terbuka tanpa batas waktu. Nilai harus diatur lebih besar dari atau sama dengan 10 menit. Kami menyarankan Nilai antara 20 menit dan 24 jam. Properti PortReuseMode ini memungkinkan SDK untuk menggunakan kumpulan kecil port sementara untuk berbagai titik akhir tujuan Azure Cosmos DB.
Gunakan Asinkron/Await Hindari memblokir panggilan: Task.Result, Task.Wait, dan Task.GetAwaiter().GetResult(). Seluruh tumpukan panggilan asinkron untuk mendapatkan manfaat dari pola asinkron/await. Banyak panggilan pemblokiran sinkron menyebabkan kurangnya Kumpulan Utas dan waktu respons yang menurun.
Batas Waktu End-to-End Untuk mendapatkan batas waktu end-to-end, Anda perlu menggunakan RequestTimeout parameter dan CancellationToken . Untuk detail selengkapnya , kunjungi panduan pemecahan masalah batas waktu kami.
Logika Coba Lagi Untuk informasi selengkapnya tentang kesalahan mana yang akan dicoba lagi dan mana yang dicoba ulang oleh SDK, lihat panduan desain. Untuk akun yang dikonfigurasi dengan beberapa wilayah, ada beberapa skenario di mana SDK akan secara otomatis mencoba kembali di wilayah lain. Untuk detail implementasi spesifik .NET, kunjungi repositori sumber SDK.
Database penembolokan/nama koleksi Ambil nama database dan kontainer Anda dari konfigurasi atau simpan nama tersebut di cache saat memulai. Panggilan seperti ReadDatabaseAsync atau ReadDocumentCollectionAsync dan CreateDatabaseQuery atau CreateDocumentCollectionQuery akan menghasilan panggilan metadata ke layanan yang menggunakan batas RU yang dicadangkan sistem. CreateIfNotExist juga hanya boleh digunakan sekali untuk menyiapkan database. Secara keseluruhan, operasi ini tidak boleh dilakukan terlalu sering.
Dukungan Massal Dalam skenario di mana Anda mungkin tidak perlu mengoptimalkan latensi, kami sarankan untuk mengaktifkan Dukungan massal untuk membuang data dalam volume besar.
Kueri Paralel Azure Cosmos DB SDK mendukung menjalankan kueri secara paralel untuk latensi dan throughput yang lebih baik pada kueri Anda. Kami menyarankan untuk mengatur properti MaxConcurrency dalam QueryRequestsOptions ke jumlah partisi yang Anda miliki. Jika Anda tidak mengetahui jumlah partisi, mulailah dengan menggunakan int.MaxValue, yang akan memberi Anda latensi terbaik. Kemudian kurangi jumlahnya hingga sesuai dengan pembatasan sumber daya lingkungan untuk menghindari masalah CPU yang tinggi. Selain itu, atur ke MaxBufferedItemCount jumlah hasil yang diharapkan yang dikembalikan untuk membatasi jumlah hasil yang telah diambil sebelumnya.
Backoff Pengujian Performa Saat melakukan pengujian pada aplikasi Anda, Anda harus menerapkan backoff pada interval RetryAfter. Menghormati backoff membantu memastikan bahwa Anda menghabiskan sedikit waktu menunggu di antara percobaan ulang.
Pengindeksan Kebijakan pengindeksan Azure Cosmos DB juga memungkinkan Anda menentukan jalur dokumen mana yang akan disertakan atau dikecualikan dari pengindeksan dengan menggunakan jalur pengindeksan (IndexingPolicy.IncludedPaths dan IndexingPolicy.ExcludedPaths). Pastikan Anda mengecualikan jalur yang tidak digunakan dari pengindeksan untuk penulisan yang lebih cepat. Untuk informasi selengkapnya tentang cara membuat indeks menggunakan SDK, lihat tips performa .NET SDK v3.
Ukuran Dokumen Biaya permintaan dari operasi tertentu berkorelasi langsung dengan ukuran dokumen. Sebaiknya kurangi ukuran dokumen Anda karena operasi pada dokumen besar lebih mahal daripada operasi pada dokumen yang lebih kecil.
Menambah jumlah utas/tugas Karena panggilan ke Azure Cosmos DB dilakukan melalui jaringan, Anda mungkin perlu variasi tingkat konkurensi permintaan sehingga aplikasi klien menghabiskan waktu tunggu minimal di antara permintaan. Contohnya, jika Anda menggunakan .NET Task Parallel Library, buat ratusan tugas yang dibaca dari atau ditulis ke Azure Cosmos DB.
Mengaktifkan Metrik Kueri Untuk lebih banyak pengelogan eksekusi kueri backend Anda, Anda dapat mengaktifkan Metrik Kueri SQL menggunakan .NET SDK kami. Untuk informasi selengkapnya tentang cara mengumpulkan Metrik Kueri SQL, lihat metrik dan performa kueri.
Pengelogan SDK Diagnostik SDK log untuk skenario yang luar biasa, seperti pengecualian atau saat permintaan melampaui latensi yang diharapkan.
DefaultTraceListener DefaultTraceListener menimbulkan masalah performa pada lingkungan produksi yang menyebabkan penyempitan CPU dan I/O yang tinggi. Pastikan Anda menggunakan versi SDK terbaru atau menghapus DefaultTraceListener dari aplikasi Anda
Hindari menggunakan karakter khusus dalam pengidentifikasi Beberapa karakter dibatasi dan tidak dapat digunakan dalam beberapa pengidentifikasi: '/', '\', '?', '#'. Rekomendasi umumnya adalah untuk tidak menggunakan karakter khusus dalam pengidentifikasi seperti nama database, nama koleksi, id item, atau kunci partisi untuk menghindari perilaku yang tidak terduga.

Menangkap diagnostik

Semua respons di SDK, termasuk, seperti CosmosException, memiliki properti Diagnostics. Properti ini mencatat semua informasi yang terkait dengan permintaan tunggal termasuk jika ada pencobaan ulang atau kegagalan sementara.

Diagnostik dikembalikan sebagai string. String berubah dengan setiap versi, karena ditingkatkan untuk memecahkan masalah skenario yang berbeda. Dengan setiap versi SDK, string akan memiliki perubahan melanggar format. Jangan mengurai string untuk menghindari kerusakan perubahan. Contoh kode berikut menunjukkan cara membaca log diagnostik menggunakan SDK .NET:

try
{
    ItemResponse<Book> response = await this.Container.CreateItemAsync<Book>(item: testItem);
    if (response.Diagnostics.GetClientElapsedTime() > ConfigurableSlowRequestTimeSpan)
    {
        // Log the response.Diagnostics.ToString() and add any additional info necessary to correlate to other logs 
    }
}
catch (CosmosException cosmosException)
{
    // Log the full exception including the stack trace with: cosmosException.ToString()
    
    // The Diagnostics can be logged separately if required with: cosmosException.Diagnostics.ToString()
}

// When using Stream APIs
ResponseMessage response = await this.Container.CreateItemStreamAsync(partitionKey, stream);
if (response.Diagnostics.GetClientElapsedTime() > ConfigurableSlowRequestTimeSpan || !response.IsSuccessStatusCode)
{
    // Log the diagnostics and add any additional info necessary to correlate to other logs with: response.Diagnostics.ToString()
}

Praktik terbaik untuk koneksi HTTP

.NET SDK menggunakan HttpClient untuk melakukan permintaan HTTP terlepas dari mode konektivitas yang dikonfigurasi. Dalam mode Langsung HTTP digunakan untuk operasi metadata dan dalam mode Gateway, http digunakan untuk operasi bidang data dan metadata. Salah satu dasar HttpClient adalah memastikan HttpClient dapat bereaksi terhadap perubahan DNS pada akun Anda dengan menyesuaikan masa pakai koneksi yang dikumpulkan. Selama koneksi terkumpul tetap terbuka, koneksi tersebut tidak bereaksi terhadap perubahan DNS. Pengaturan ini memaksa koneksi terkumpul ditutup secara berkala, memastikan bahwa aplikasi Anda bereaksi terhadap perubahan DNS. Rekomendasi kami adalah Anda menyesuaikan nilai ini sesuai dengan mode konektivitas dan beban kerja Anda untuk menyeimbangkan dampak performa dari sering membuat koneksi baru, dengan perlu bereaksi terhadap perubahan DNS (ketersediaan). Nilai 5 menit akan menjadi awal yang baik yang dapat ditingkatkan jika memengaruhi performa terutama untuk mode Gateway.

Anda dapat menyuntikkan HttpClient kustom Anda melalui CosmosClientOptions.HttpClientFactory, misalnya:

// Use a Singleton instance of the SocketsHttpHandler, which you can share across any HttpClient in your application
SocketsHttpHandler socketsHttpHandler = new SocketsHttpHandler();
// Customize this value based on desired DNS refresh timer
socketsHttpHandler.PooledConnectionLifetime = TimeSpan.FromMinutes(5);

CosmosClientOptions cosmosClientOptions = new CosmosClientOptions()
{
    // Pass your customized SocketHttpHandler to be used by the CosmosClient
    // Make sure `disposeHandler` is `false`
    HttpClientFactory = () => new HttpClient(socketsHttpHandler, disposeHandler: false)
};

// Use a Singleton instance of the CosmosClient
return new CosmosClient("<connection-string>", cosmosClientOptions);

Jika Anda menggunakan injeksi dependensi .NET, Anda dapat menyederhanakan proses Singleton:

SocketsHttpHandler socketsHttpHandler = new SocketsHttpHandler();
// Customize this value based on desired DNS refresh timer
socketsHttpHandler.PooledConnectionLifetime = TimeSpan.FromMinutes(5);
// Registering the Singleton SocketsHttpHandler lets you reuse it across any HttpClient in your application
services.AddSingleton<SocketsHttpHandler>(socketsHttpHandler);

// Use a Singleton instance of the CosmosClient
services.AddSingleton<CosmosClient>(serviceProvider =>
{
    SocketsHttpHandler socketsHttpHandler = serviceProvider.GetRequiredService<SocketsHttpHandler>();
    CosmosClientOptions cosmosClientOptions = new CosmosClientOptions()
    {
        HttpClientFactory = () => new HttpClient(socketsHttpHandler, disposeHandler: false)
    };

    return new CosmosClient("<connection-string>", cosmosClientOptions);
});

Praktik terbaik saat menggunakan mode Gateway

Tingkatkan System.Net MaxConnections per host saat Anda menggunakan mode Gateway. Permintaan Azure Cosmos DB dibuat melalui HTTPS/REST saat Anda menggunakan mode Gateway. Mereka tunduk pada batas koneksi default per nama host atau alamat IP. Anda mungkin perlu mengatur MaxConnections ke nilai yang lebih tinggi (dari 100 hingga 1.000) sehingga pustaka klien dapat menggunakan beberapa koneksi simultan ke Azure Cosmos DB. Di .NET SDK 1.8.0 dan yang lebih baru, nilai default untuk ServicePointManager.DefaultConnectionLimit adalah 50. Untuk mengubah nilai, Anda bisa mengatur CosmosClientOptions.GatewayModeMaxConnectionLimit ke nilai yang lebih tinggi.

Praktik terbaik untuk beban kerja tulis-berat

Untuk beban kerja yang memiliki muatan buat berat, atur opsi permintaan EnableContentResponseOnWrite ke false. Layanan tidak akan lagi mengembalikan sumber daya yang dibuat atau diperbarui ke SDK. Biasanya, karena aplikasi memiliki objek yang sedang dibuat, layanan tidak perlu mengembalikannya. Nilai header masih dapat diakses, seperti biaya permintaan. Menonaktifkan respons konten dapat membantu meningkatkan performa, karena SDK tidak lagi perlu mengalokasikan memori atau serialisasi isi respons. Ini juga mengurangi penggunaan bandwidth jaringan untuk lebih membantu performa.

Penting

Pengaturan EnableContentResponseOnWrite ke false juga akan menonaktifkan respons dari operasi pemicu.

Praktik terbaik untuk aplikasi multi-penyewa

Aplikasi yang mendistribusikan penggunaan di beberapa penyewa di mana setiap penyewa diwakili oleh database, kontainer, atau kunci partisi yang berbeda dalam akun Azure Cosmos DB yang sama harus menggunakan satu instans klien. Satu instans klien dapat berinteraksi dengan semua database, kontainer, dan kunci partisi dalam akun, dan praktik terbaik adalah menggunakan pola singleton.

Namun, ketika setiap penyewa diwakili oleh akun Azure Cosmos DB yang berbeda, diperlukan untuk membuat instans klien terpisah per akun. Pola singleton masih berlaku untuk setiap klien (satu klien untuk setiap akun selama masa pakai aplikasi), tetapi jika volume penyewa tinggi, jumlah klien bisa sulit dikelola. Koneksi dapat meningkat di luar batas lingkungan komputasi dan menyebabkan masalah konektivitas.

Disarankan dalam kasus ini untuk:

  • Pahami batasan lingkungan komputasi (CPU dan sumber daya koneksi). Sebaiknya gunakan VM dengan setidaknya 4 core dan memori 8 GB jika memungkinkan.
  • Berdasarkan batasan lingkungan komputasi, tentukan jumlah instans klien (dan oleh karena itu jumlah penyewa) yang dapat ditangani instans komputasi tunggal. Anda dapat memperkirakan jumlah koneksi yang akan dibuka per klien tergantung pada mode koneksi yang dipilih.
  • Mengevaluasi distribusi penyewa di seluruh instans. Jika setiap instans komputasi berhasil menangani sejumlah penyewa, penyeimbangan beban, dan perutean penyewa tertentu ke instans komputasi yang berbeda akan memungkinkan penskalaan saat jumlah penyewa bertambah.
  • Untuk beban kerja yang jarang, pertimbangkan untuk menggunakan cache Yang Paling Jarang Digunakan sebagai struktur untuk menahan instans klien dan membuang klien untuk penyewa yang belum diakses dalam jendela waktu. Salah satu opsi di .NET adalah MemoryCacheEntryOptions, di mana RegisterPostEvictionCallback dapat digunakan untuk membuang klien yang tidak aktif dan SetSlidingExpiration dapat digunakan untuk menentukan waktu maksimum untuk menahan koneksi yang tidak aktif.
  • Evaluasi menggunakan mode Gateway untuk mengurangi jumlah koneksi jaringan.
  • Saat menggunakan mode Langsung , pertimbangkan untuk menyesuaikan CosmosClientOptions.IdleTcpConnectionTimeout dan CosmosClientOptions.PortReuseMode pada konfigurasi mode langsung untuk menutup koneksi yang tidak digunakan dan menjaga volume koneksi tetap terkendali.

Langkah berikutnya

Untuk contoh aplikasi yang digunakan untuk mengevaluasi Azure Cosmos DB untuk skenario kinerja tinggi pada beberapa mesin klien, lihat Pengujian kinerja dan skala dengan Azure Cosmos DB.

Untuk mempelajari selengkapnya tentang perancangan aplikasi Anda untuk skala dan kinerja tinggi, lihat Pemartisian dan penyekalaan di Azure Cosmos DB.

Mencoba melakukan perencanaan kapasitas untuk migrasi ke Azure Cosmos DB? Anda dapat menggunakan informasi tentang kluster database Anda yang ada saat ini untuk perencanaan kapasitas.