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

適用対象: NoSQL

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

Azure Cosmos DB エンジニアからの .NET SDK の使用の詳細については、次のビデオをご覧ください。

チェック リスト

診断をキャプチャする

CosmosException を含む SDK のすべての応答には、Diagnostics プロパティがあります。 このプロパティでは、再試行または一時的な失敗があるかどうかなど、1 つの要求に関連するすべての情報が記録されます。

診断は文字列として返されます。 文字列は、さまざまなシナリオのトラブルシューティングに対応するために改良されるので、バージョンによって異なります。 SDK の各バージョンでは、文字列の書式設定に重大な変更が加えられる予定です。 破壊的変更を避けるために、文字列を解析しないでください。 次のコード サンプルは、.NET SDK を使用して診断ログを読み取る方法を示しています。

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()
}

HTTP 接続のベスト プラクティス

.NET SDK では、構成されている接続モードに関係なく、HttpClient を使用して HTTP 要求を実行します。

• 直接モードでは、HTTP はメタデータ操作に使用されます
• ゲートウェイ モードでは、データ プレーン操作とメタデータ操作の両方に HTTP が使用されます

HttpClient の基礎の 1 つは、HttpClientことで、 がアカウントの DNS 変更に対応できるようにすることです。 プールされた接続が開いたままになっている限り、DNS の変更には対応しません。 この設定により、プールされた接続が定期的に閉じられ、アプリケーションが DNS の変更に確実に対応できるようになります。 この値は 、接続モード とワークロードに応じてカスタマイズし、新しい接続を頻繁に作成する場合のパフォーマンス効果と、DNS の変更 (可用性) に対応する必要がある場合のパフォーマンスのバランスを取ることで推奨されます。 5 分の値は、特にゲートウェイ モードの場合、パフォーマンスに影響を与える場合に増やすことができる適切な開始になります。

次のように、CosmosClientOptions.HttpClientFactory を使用してカスタム HttpClient を挿入できます。

// 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);

.NET 依存関係の挿入を使用する場合は、シングルトン プロセスを簡略化できます。

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);
});

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

ゲートウェイ モードを使用する場合は、ホストごとに System.Net MaxConnections を増やします。 ゲートウェイ モードを使用すると、Azure Cosmos DB の要求は HTTPS/REST を介して行われます。 それらは、ホスト名または IP アドレスごとの既定の接続数の上限に従います。 場合によっては、Azure Cosmos DB に対する複数の同時接続をクライアント ライブラリで使用できるよう、MaxConnections を高い値 (100 ～ 1,000) に増やす必要があります。 .NET SDK 1.8.0 以降では、ServicePointManager.DefaultConnectionLimit の既定値は 50 です。 値を変更するには、CosmosClientOptions.GatewayModeMaxConnectionLimit を高い値に設定します。

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

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

マルチテナント アプリケーションのベスト プラクティス

同じ Azure Cosmos DB アカウント内で、異なるデータベース、コンテナー、またはパーティション キーによって各テナントが表される複数のテナントに使用量を分散するアプリケーションは、1 つのクライアント インスタンスを使用する必要があります。 1 つのクライアント インスタンスは、アカウント内のすべてのデータベース、コンテナー、パーティション キーと対話できます。シングルトン パターンを使用することをお勧めします。

ただし、各テナントが異なる Azure Cosmos DB アカウントによって表されるときは、アカウントごとに別個のクライアント インスタンスを作成する必要があります。 それでもシングルトン パターンは各クライアントに適用されますが (アプリケーションの有効期間中アカウントごとに 1 つのクライアント)、テナントのボリュームが多い場合は、クライアントの数を管理するのが困難になる可能性があります。 接続がコンピューティング環境の限界を超えて増加して、接続の問題を引き起こす可能性があります。

このような場合は、次を行うことをお勧めします。

• コンピューティング環境 (CPU と接続リソース) の限界を把握します。 可能な限り、少なくとも 4 コアと 8 GB のメモリを備えた VM を使用することをお勧めします。
• コンピューティング環境の限界に基づいて、1 つのコンピューティング インスタンスで処理できるクライアント インスタンスの数 (つまりテナントの数) を決定します。 選択した接続モードに応じて、クライアントごとに開く接続 の数を見積も ることができます。
• インスタンス間のテナントの分散を評価します。 各コンピューティング インスタンスが特定の限られた量のテナントを正常に処理できる場合、テナントの負荷分散と異なるコンピューティング インスタンスへのルーティングにより、テナント数の増加に応じてスケーリングが可能になります。
• スパース ワークロードの場合は、クライアント インスタンスを保持し、時間枠内にアクセスされないテナントのクライアントを破棄する構造として、最も使用頻度の低いキャッシュを使用することを検討してください。 .NET での 1 つの選択肢は MemoryCacheEntryOptions です。これは RegisterPostEvictionCallback を使用して非アクティブなクライアントを破棄し、SetSlidingExpiration を使用して非アクティブな接続を保持する最大時間を定義できます。
• ゲートウェイ モードを使用して評価し、ネットワーク接続の数を減らします。
• ダイレクト モードを使用する場合は、Direct モード構成で CosmosClientOptions.IdleTcpConnectionTimeout と CosmosClientOptions.PortReuseMode を調整して、未使用の接続を閉じ、接続のボリュームを制御下に保つことを検討してください。

次のステップ

• ベンチマーク フレームワークを使用して Azure Cosmos DB for NoSQL のパフォーマンスを測定する
• Azure Cosmos DB でのパーティション分割と水平スケーリング

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

• 現在のデータベース ワークロードの一般的な要求レートがわかっている場合は、「Azure Cosmos DB Capacity Planner を使用した RU/秒の見積もり」を参照してください