Menyetel konfigurasi koneksi untuk Azure Cosmos DB Java SDK v4

  • Artikel

BERLAKU UNTUK: NoSQL

Penting

Tips performa dalam artikel ini hanya untuk Azure Cosmos DB Java SDK v4. Silakan lihat Catatan rilis Azure Cosmos DB Java SDK v4, repositori Maven, dan panduan pemecahan masalah Azure Cosmos DB Java SDK v4 untuk informasi selengkapnya. Jika saat ini Anda menggunakan versi yang lebih lama dari v4, lihat panduan Migrasi ke Azure Cosmos DB Java SDK v4 untuk bantuan peningkatan ke v4.

Azure Cosmos DB adalah database terdistribusi yang cepat dan fleksibel yang menskalakan secara mulus dengan latensi dan throughput terjamin. Anda tidak perlu membuat perubahan arsitektur besar atau menulis kode kompleks untuk menskalakan database dengan Azure Cosmos DB. Penskalaan naik dan turun semudah melakukan satu panggilan API atau panggilan metode SDK. Namun, karena Azure Cosmos DB diakses melalui panggilan jaringan, ada konfigurasi koneksi yang dapat Anda sesuaikan untuk mencapai performa puncak saat menggunakan Azure Cosmos DB Java SDK v4.

Konfigurasi koneksi

Catatan

Di Azure Cosmos DB Java SDK v4, mode Langsung adalah pilihan terbaik untuk meningkatkan performa database dengan sebagian besar beban kerja.

Untuk mempelajari selengkapnya tentang opsi konektivitas yang berbeda, lihat artikel mode konektivitas.

Mode koneksi langsung

Mode koneksi default Java SDK adalah langsung. Permintaan Azure Cosmos DB mode langsung dibuat melalui TCP saat menggunakan Azure Cosmos DB Java SDK v4. Mode Langsung internal menggunakan arsitektur khusus untuk mengelola sumber daya jaringan secara dinamis dan mendapatkan performa terbaik. Arsitektur sisi klien yang digunakan dalam mode Langsung memungkinkan pemanfaatan jaringan yang dapat diprediksi dan akses multipleks ke replika Azure Cosmos DB. Untuk mempelajari selengkapnya tentang arsitektur, lihat arsitektur koneksi mode langsung

Anda dapat mengonfigurasi mode koneksi di penyusun klien menggunakan metode directMode() seperti yang ditunjukkan di bawah ini. Untuk mengonfigurasi mode langsung dengan pengaturan default, panggil directMode() metode tanpa argumen. Untuk menyesuaikan pengaturan koneksi mode langsung, lewati DirectConnectionConfig ke directMode() API.

Java SDK V4 (Maven com.azure::azure-cosmos) API Asinkron


/* Direct mode, default settings */
CosmosAsyncClient clientDirectDefault = new CosmosClientBuilder()
        .endpoint(HOSTNAME)
        .key(MASTERKEY)
        .consistencyLevel(CONSISTENCY)
        .directMode()
        .buildAsyncClient();

/* Direct mode, custom settings */
DirectConnectionConfig directConnectionConfig = DirectConnectionConfig.getDefaultConfig();

// Example config, do not use these settings as defaults
directConnectionConfig.setMaxConnectionsPerEndpoint(130);
directConnectionConfig.setIdleConnectionTimeout(Duration.ZERO);

CosmosAsyncClient clientDirectCustom = new CosmosClientBuilder()
        .endpoint(HOSTNAME)
        .key(MASTERKEY)
        .consistencyLevel(CONSISTENCY)
        .directMode(directConnectionConfig)
        .buildAsyncClient();

/* Gateway mode, default settings */
CosmosAsyncClient clientGatewayDefault = new CosmosClientBuilder()
        .endpoint(HOSTNAME)
        .key(MASTERKEY)
        .consistencyLevel(CONSISTENCY)
        .gatewayMode()
        .buildAsyncClient();

/* Gateway mode, custom settings */
GatewayConnectionConfig gatewayConnectionConfig = GatewayConnectionConfig.getDefaultConfig();

// Example config, do not use these settings as defaults
gatewayConnectionConfig.setProxy(new ProxyOptions(ProxyOptions.Type.HTTP, InetSocketAddress.createUnresolved("your.proxy.addr",80)));
gatewayConnectionConfig.setMaxConnectionPoolSize(1000);

CosmosAsyncClient clientGatewayCustom = new CosmosClientBuilder()
        .endpoint(HOSTNAME)
        .key(MASTERKEY)
        .consistencyLevel(CONSISTENCY)
        .gatewayMode(gatewayConnectionConfig)
        .buildAsyncClient();

/* No connection mode, defaults to Direct mode with default settings */
CosmosAsyncClient clientDefault = new CosmosClientBuilder()
        .endpoint(HOSTNAME)
        .key(MASTERKEY)
        .consistencyLevel(CONSISTENCY)
        .buildAsyncClient();

Menyesuaikan mode koneksi langsung

Jika perilaku mode Langsung non-default diinginkan, buat instans DirectConnectionConfig dan sesuaikan propertinya, kemudian berikan instans properti yang disesuaikan ke metode directMode() di penyusun klien Azure Cosmos DB.

Pengaturan konfigurasi ini mengontrol perilaku arsitektur mode Langsung yang mendasari yang dibahas di atas.

Sebagai langkah pertama, gunakan pengaturan konfigurasi yang disarankan berikut di bawah ini. Opsi DirectConnectionConfig ini adalah pengaturan konfigurasi lanjutan yang dapat memengaruhi performa SDK dengan cara yang tidak terduga; kami menyarankan pengguna untuk tidak memodifikasinya, kecuali mereka merasa sangat nyaman dalam memahami keseimbangan dan itu benar-benar diperlukan. Silakan hubungi tim Azure Cosmos DB jika Anda mengalami masalah pada topik khusus ini.

Opsi konfigurasi Default Disarankan Detail
idleConnectionTimeout "PT0" (ZERO) "PT0" (ZERO) Ini menunjukkan durasi batas waktu koneksi diam untuk satu koneksi ke titik akhir/node backend (mewakili replika). Secara default, SDK tidak secara otomatis menutup koneksi diam ke simpul backend.
idleEndpointTimeout "PT1H" "PT1H" Ini menunjukkan durasi batas waktu koneksi diam untuk kumpulan koneksi untuk titik akhir/simpul backend (mewakili replika). Secara default, jika tidak ada permintaan masuk ke simpul titik akhir/backend tertentu, SDK akan menutup semua koneksi di kumpulan koneksi ke simpul titik akhir/backend tersebut setelah 1 jam untuk menghemat sumber daya jaringan dan biaya I/O. Untuk pola lalu lintas yang jarang atau sporadis, sebaiknya atur nilai ini ke angka yang lebih tinggi seperti 6 jam, 12 jam atau bahkan 24 jam, sehingga SDK tidak perlu sering membuka koneksi. Namun, ini akan menggunakan sumber daya jaringan dan akan memiliki jumlah koneksi yang lebih tinggi yang tetap terbuka pada waktu tertentu. Jika ini diatur ke ZERO, pemeriksaan titik akhir diam akan dinonaktifkan.
maxConnectionsPerEndpoint "130" "130" Ini mewakili ukuran terikat atas kumpulan koneksi untuk titik akhir/simpul backend (mewakili replika). SDK membuat koneksi ke node titik akhir/backend sesuai permintaan dan berdasarkan permintaan bersamaan yang masuk. Secara default, jika diperlukan, SDK akan membuat maksimum 130 koneksi ke titik akhir/simpul backend. (CATATAN: SDK tidak membuat 130 koneksi ini di muka).
maxRequestsPerConnection "30" "30" Ini menunjukkan ukuran batas atas dari jumlah maksimum permintaan yang dapat diantrekan pada satu koneksi untuk titik akhir/node backend tertentu (mewakili replika). SDK mengantre permintaan ke satu koneksi ke node titik akhir/backend sesuai permintaan dan berdasarkan permintaan bersamaan yang masuk. Secara default, jika diperlukan, SDK akan mengantre maksimum 30 permintaan ke satu koneksi untuk titik akhir/node backend tertentu. (CATATAN: SDK tidak mengantrekan 30 permintaan ini ke satu koneksi di muka).
connectTimeout "PT5S" "~PT1S" Ini mewakili durasi batas waktu pembentukan koneksi untuk satu koneksi yang akan dibuat dengan titik akhir/simpul backend. Secara default SDK akan menunggu maksimal 5 detik untuk pembentukan koneksi sebelum melemparkan kesalahan. Pembentukan koneksi TCP menggunakan jabat tangan multi-langkah yang meningkatkan latensi waktu pembentukan koneksi, oleh karena itu, pelanggan disarankan untuk menetapkan nilai ini sesuai dengan bandwidth jaringan dan pengaturan lingkungan mereka. CATATAN: Rekomendasi ~PT1S ini hanya untuk aplikasi yang disebarkan di wilayah kolokasi akun Cosmos DB mereka.
networkRequestTimeout "PT5S" "PT5S" Ini mewakili durasi batas waktu jaringan untuk satu permintaan. SDK akan menunggu maksimum selama durasi ini untuk menggunakan respons layanan setelah permintaan ditulis ke koneksi jaringan. SDK hanya memungkinkan nilai antara 1 detik (min) dan 10 detik (maks). Mengatur nilai terlalu tinggi dapat mengakibatkan lebih sedikit percobaan ulang dan mengurangi kemungkinan keberhasilan dengan mencoba kembali.

Mode Koneksi Gateway

Operasi sarana kontrol seperti database dan kontainer CRUD selalu menggunakan mode Gateway. Bahkan ketika pengguna telah mengonfigurasi mode Langsung untuk operasi sarana data, sarana kontrol dan operasi data meta menggunakan pengaturan mode Gateway default. Ini cocok untuk sebagian besar pengguna. Namun, pengguna yang menginginkan mode Langsung untuk operasi sarana data serta kesesuaian parameter mode Gateway sarana kontrol dapat menggunakan ambil alih directMode() berikut:

Java SDK V4 (Maven com.azure::azure-cosmos) API Asinkron


/* Independent customization of Direct mode data plane and Gateway mode control plane */
DirectConnectionConfig directConnectionConfig = DirectConnectionConfig.getDefaultConfig();

// Example config, do not use these settings as defaults
directConnectionConfig.setMaxConnectionsPerEndpoint(130);
directConnectionConfig.setIdleConnectionTimeout(Duration.ZERO);

GatewayConnectionConfig gatewayConnectionConfig = GatewayConnectionConfig.getDefaultConfig();

// Example config, do not use these settings as defaults
gatewayConnectionConfig.setProxy(new ProxyOptions(ProxyOptions.Type.HTTP, InetSocketAddress.createUnresolved("your.proxy.addr",80)));
gatewayConnectionConfig.setMaxConnectionPoolSize(1000);

CosmosAsyncClient clientDirectCustom = new CosmosClientBuilder()
        .endpoint(HOSTNAME)
        .key(MASTERKEY)
        .consistencyLevel(CONSISTENCY)
        .directMode(directConnectionConfig,gatewayConnectionConfig)
        .buildAsyncClient();

Menyesuaikan mode koneksi gateway

Jika perilaku mode Gateway non-default diinginkan, buat instans GatewayConnectionConfig dan sesuaikan propertinya, lalu teruskan instans properti yang disesuaikan ke metode penimpaan directMode() di atas atau metode gatewayMode() di penyusun klien Azure Cosmos DB.

Sebagai langkah pertama, gunakan pengaturan konfigurasi yang direkomendasikan berikut ini di bawah ini. Opsi GatewayConnectionConfig ini adalah pengaturan konfigurasi tingkat lanjut yang dapat memengaruhi performa SDK dengan cara yang tidak terduga; kami menyarankan pengguna menghindari memodifikasi mereka kecuali mereka merasa sangat nyaman dalam memahami tradeoff dan itu benar-benar diperlukan. Silakan hubungi tim Azure Cosmos DB jika Anda mengalami masalah pada topik khusus ini.

Opsi konfigurasi Default Disarankan Detail
maxConnectionPoolSize "1000" "1000" Ini menunjukkan ukuran terikat atas ukuran kumpulan koneksi untuk klien http yang mendasar, yang merupakan jumlah maksimum koneksi yang akan dibuat SDK untuk permintaan masuk ke mode Gateway. SDK menggunakan kembali koneksi ini saat mengirim permintaan ke Gateway.
idleConnectionTimeout "PT60S" "PT60S" Ini menunjukkan durasi batas waktu koneksi menganggur untuk satu koneksi ke Gateway. Setelah waktu ini, koneksi akan ditutup secara otomatis dan akan dihapus dari kumpulan koneksi.

Langkah berikutnya

Untuk mempelajari selengkapnya tentang tips performa untuk Java SDK, lihat Tips performa untuk Azure Cosmos DB Java SDK v4.

Untuk mempelajari selengkapnya tentang mendesain aplikasi Anda untuk skala dan performa tinggi, lihat Pemartisian dan penskalaan 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.