Azure Cosmos DB Java SDK のベスト プラクティス

  • [アーティクル]

適用対象: NoSQL

この記事では、Azure Cosmos DB Java SDK を使用する上でのベスト プラクティスについて説明します。 これらのプラクティスに従うことで、待機時間の短縮と高可用性の実現が可能になり、全体的なパフォーマンスを向上させることができます。

チェック リスト

オン トピック 詳細/リンク
SDK バージョン 最適なパフォーマンスを実現するために、常に最新バージョンの Azure Cosmos DB SDK を使用します。
シングルトン クライアント パフォーマンスを向上させるには、ご自身のアプリケーションの有効期間中に CosmosClient の単一インスタンスを使用します。
リージョン 待機時間を短縮するには、可能な限り、Azure Cosmos DB アカウントと同じ Azure リージョンでアプリケーションを実行してください。 2 から 4 のリージョンを有効にし、複数のリージョンでアカウントをレプリケートして、可用性を最大限に高めます。 運用環境ワークロードの場合は、サービスマネージド フェールオーバーを有効にします。 この構成がない場合、リージョンに接続されていないため手動フェールオーバーは成功せず、書き込みリージョンの停止中は、アカウントで書き込みを利用できなくなる可能性があります。 Java SDK を使用して複数のリージョンを追加する方法については、こちらを参照してください
可用性とフェールオーバー V4 SDK で preferredRegions を設定します。 フェールオーバー中に、書き込み操作が現在の書き込みリージョンに送信され、すべての読み取りが優先リージョン リスト内の最初のリージョンに送信されます。 リージョン内フェールオーバー メカニズムの詳細については、可用性に関するトラブルシューティング ガイドを参照してください。
CPU クライアント マシン上のリソースが不足しているため、接続/可用性の問題に遭遇することがあります。 Azure Cosmos DB クライアントを実行しているノードで CPU 使用率を監視し、使用率が非常に高い場合はスケールアップ/スケールアウトします。
Hosting 運用環境ワークロードにおける、ほとんどの一般的なケースでは、可能な限り、少なくとも4コアと 8 GB のメモリ VM を使用することを強くお勧めします。
接続モード 最高のパフォーマンスを実現するには、直接モードを使用します。 この方法の手順については、V4 SDK のドキュメント を参照してください。
ネットワーク 仮想マシンを使用してアプリケーションを実行する場合は、VM で高速ネットワークを有効にして、高トラフィックが原因で発生するボトルネックを解消し、待機時間や CPU ジッターを減らします。 CPU の最大使用率が 70% 未満であるハイエンドな仮想マシンの使用も検討してください。
一時的なポートの不足 スパース接続または不定期接続の場合は、idleEndpointTimeout をより大きな値に設定することをお勧めします。 DirectConnectionConfig の idleEndpointTimeout プロパティは、未使用の接続を閉じるまでの時間を制御するのに役立ちます。 こうすることで、未使用の接続の数が減少します。 既定では、エンドポイントへのアイドル接続は 1 時間開いたままになります。 特定のエンドポイントへの要求がアイドル状態のエンドポイント タイムアウト期間に対して行われていない場合、ダイレクト クライアントはそのエンドポイントへのすべての接続を閉じて、リソースと I/O コストを節約します。
適切なスケジューラを使用する (イベント ループの IO Netty スレッドを盗まない) ブロックキング呼び出しを避ける.block()。 非同期 APIパターンと適切なスレッド処理とスケジューラの使用を活用するために、呼び出し履歴全体が非同期になります
エンドツーエンドのタイムアウト エンドツーエンドのタイムアウトを取得するには、Java SDK のエンドツーエンドのタイムアウト ポリシーを実装します。 Azure Cosmos DB のタイムアウトの詳細については、こちらを参照してください
再試行ロジック 一時エラーとは、その基になる原因がすぐに自動的に解決されるエラーです。 データベースに接続するアプリケーションは、これらの一時エラーを想定して構築する必要があります。 これに対処するには、アプリケーション エラーとしてユーザーに表示するのではなく、コードに再試行ロジックを実装します。 SDK には、読み取りやクエリの操作など、再試行可能な要求でこれらの一時的なエラーを処理するロジックが組み込まれています。 書き込みはべき等ではないので、SDK では、一時的なエラーでは書き込みが再試行されません。 ユーザーは、SDK を使用して、スロットルの再試行ロジックを構成できます。 再試行の対象となるエラーの詳細については、こちらを参照してください
データベース/コレクション名のキャッシュ 構成からデータベースとコンテナーの名前を取得するか、開始時にそれらをキャッシュします。 CosmosAsyncDatabase#read() や CosmosAsyncContainer#read() のような呼び出しでは、サービスに対するメタデータ呼び出しが行われ、システムで予約されている RU 制限から消費されます。 また、createDatabaseIfNotExists() は、データベースの設定に 1 回だけ使用する必要があります。 一般に、これらの操作は、頻繁に実行しないでください。
並列クエリ Azure Cosmos DB SDK では、クエリの待機時間とスループットを向上させるクエリの並列実行がサポートされています。 CosmosQueryRequestsOptions 内の maxDegreeOfParallelism プロパティ を、使用しているパーティションの数に設定することをお勧めします。 パーティションの数を把握していない場合は、値を -1 に設定すると、最適な待機時間が得られます。 また、返される結果の予想数に maxBufferedItemCount を設定して、プリフェッチされる結果の数 を制限します。
パフォーマンス テストのバックオフ アプリケーションでテストを実行する場合は、RetryAfter の間隔でバックオフを実装する必要があります。 バックオフにより、再試行までの待ち時間を最小限に抑えることができます。
インデックス作成 Azure Cosmos DB のインデックス作成ポリシーでは、IndexingPolicy#getIncludedPaths() と IndexingPolicy#getExcludedPaths() のインデックス作成パスを使用して、インデックス作成に含めたり除外したりするドキュメント パスも指定できます。 書き込みを高速化するには、インデックス作成から未使用のパスを除外ししてください。 SDK を使用してインデックスを作成する方法のサンプルについては、こちらを参照してください
ドキュメント サイズ 特定の操作の要求の料金は、ドキュメントのサイズに直接関係します。 サイズの大きいドキュメントの操作は、サイズの小さいドキュメントの操作よりもコストがかかるので、ドキュメントのサイズを小さくすることをお勧めします。
Page Size 既定では、100 項目または 4 MB (先に達した方) のチャンク単位でクエリ結果が返されます。 クエリから返される項目が 100 個を超える場合は、ページ サイズを大きくして、必要なラウンド トリップの数を減らします。 ページ サイズが大きくなると、メモリ消費量が増えます。
クエリ メトリックの有効化 バックエンド クエリ実行の追加ログ記録については、 Java SDKを使用して SQL クエリ メトリックをキャプチャする手順に従ってください
SDK のログ SDK のログを使用して、追加の診断情報をキャプチャし、待機時間の問題をトラブルシューティングします。 Java SDK の CosmosDiagnostics をログに記録し、サービスに対する現在の要求について、詳細な Azure Cosmos DB 診断情報を取得します。 使用例として、CosmosDiagnostics#getDuration() が指定されたしきい値を超える場合、例外や完了した操作で診断をキャプチャします。 つまり、SLA が 10 秒の場合、getDuration()> 10 秒のときに診断をキャプチャします。 これらの診断は、パフォーマンス テスト中にのみ使用することをお勧めします。 詳細については、「Java SDK での診断キャプチャ」を参照してください
識別子で特殊文字を使用しないようにしてください 一部の文字は制限されており、 '/'、'\'、'?'、'#' は識別子では使用できません。 一般的に推奨されるのは、予期しない動作を回避するために、データベース名、コレクション名、項目 ID、パーティション キーなどの識別子に特殊文字を使用しないことです。

ゲートウェイ モードを使用する場合のベスト プラクティス

ゲートウェイ モードを使用すると、Azure Cosmos DB の要求は HTTPS/REST を介して行われます。 それらは、ホスト名または IP アドレスごとの既定の接続数の上限に従います。 場合によっては、Azure Cosmos DB に対する複数の同時接続をクライアント ライブラリで使用できるように、maxConnectionPoolSize を異なる値 (100 から 1,000 まで) に調整する必要があります。 Java v4 SDK では、の GatewayConnectionConfig#maxConnectionPoolSize 既定値は 1000 です。 値を変更するには、GatewayConnectionConfig#maxConnectionPoolSize を異なる値に設定します。

書き込み負荷の高いワークロードのベスト プラクティス

高負荷の作成ペイロードがあるワークロードでは、CosmosClientBuilder#contentResponseOnWriteEnabled() 要求オプションを false に設定します。 サービスは、作成または更新されたリソースを SDK に返さなくなります。 通常、アプリケーションには作成済みのオブジェクトがあるため、サービスから返される必要はありません。 ヘッダー値には、まだ要求の料金と同様にアクセスできます。 応答コンテンツを無効にすると、SDK がメモリを割り当てたり応答の本文をシリアル化したりする必要がなくなるため、パフォーマンスを向上させることができます。 また、ネットワーク帯域幅の使用量も削減され、パフォーマンスがさらに向上します。

次のステップ

Java SDK のパフォーマンスに関するヒントの詳細については、「Azure Cosmos DB Java SDK v4 のパフォーマンスに関するヒント」を参照してください。

スケーリングと高パフォーマンスのためのアプリケーションの設計について詳しくは、「Azure Cosmos DB でのパーティション分割とスケーリング」をご覧ください。

Azure Cosmos DB への移行のための容量計画を実行しようとしていますか? 容量計画のために、既存のデータベース クラスターに関する情報を使用できます。