Azure Cosmos DB .NET SDK の使用時の問題を診断しトラブルシューティングする

[アーティクル]
08/15/2024

適用対象: NoSQL

この記事では、Azure Cosmos DB for NoSQL アカウントで .NET SDK を使用するときの一般的な問題、回避策、診断手順、およびツールについて説明します。 .NET SDK には、Azure Cosmos DB for NoSQL にアクセスするためのクライアント側の論理表現が用意されています。この記事では、問題が発生した場合に役立つツールとアプローチについて説明します。

問題をトラブルシューティングするためのチェックリスト

運用環境にアプリケーションを移行する前に、次のチェックリストを検討してください。チェックリストを使用すればと、発生する可能性のある一般的な問題のいくつかを防止できます。問題が発生したときにもすばやく診断できます。

最新の SDK を使用します。プレビュー SDK は運用環境で使用しないでください。これにより、既に修正されている既知の問題の発生が防止されます。
パフォーマンスに関するヒントを確認し、推奨される方法に従います。これは、スケーリング、待機時間、その他のパフォーマンス上の問題の防止に役立ちます。
問題のトラブルシューティングに役立つ SDK のログ機能を有効にします。ログ機能を有効にするとパフォーマンスに影響することがあるため、問題のトラブルシューティング時にのみ有効にすることをお勧めします。次のログを有効にできます。
- Azure portal を使用してメトリックを記録します。ポータルのメトリックは Azure Cosmos DB テレメトリを表示します。これは、問題が Azure Cosmos DB に対応したものか、クライアント側から発生したものかを判断する場合に役立ちます。
- 操作や例外から診断文字列をログに記録します。

この記事の一般的な問題と対処法のセクションを確認します。

アクティブに監視されている GitHub の問題セクションを調べます。回避策が既に提出済みの同様の問題がないか確認します。ソリューションが見つからなかった場合は、GitHub の問題を提出してください。緊急の問題のサポートのティックを開くことができます。

診断をキャプチャする

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

一般的な問題と対処法

一般的な推奨事項

例外の詳細に含まれる aka.ms リンクに従います。
可能なときはいつでも、Azure Cosmos DB アカウントと同じ Azure リージョンでアプリを実行します。
クライアントマシン上のリソースが不足しているため、接続/可用性の問題に遭遇することがあります。 Azure Cosmos DB クライアントを実行しているノードの CPU 使用率を監視し、高負荷で実行している場合にはスケールアップ/アウトを実行することをお勧めします。

ポータルのメトリックを確認する

ポータルのメトリックを確認すると、クライアント側の問題であるか、サービスに問題があるかの判断に役立ちます。たとえば、要求が調整されていることを意味する、高いレートのレート制限された要求 (HTTP 状態コード 429) がメトリックに含まれていれば、"要求率が大きすぎる" に関するセクションを確認してください。

再試行の設計

耐障害性のあるアプリケーションの設計方法に関するガイダンスについては、Azure Cosmos DB SDK での耐障害性のあるアプリケーションの設計に関するガイドを参照してください。また SDK の再試行セマンティクスの内容について学習してください。

SNAT

パブリック IP アドレスを使用しない Azure Virtual Machines にアプリをデプロイした場合、既定では、Azure SNAT ポートによって VM 外の任意のエンドポイントへの接続が確立されます。 VM から Azure Cosmos DB エンドポイントへの許可される接続の数は、Azure SNAT 構成によって制限されます。このような状況では、接続の調整、接続の終了、または上記の要求タイムアウトが発生する可能性があります。

Azure SNAT ポートが使用されるのは、プライベート IP アドレスを持つ VM がパブリック IP アドレスに接続しようとしている場合に限られます。 Azure SNAT の制限を回避するには、次の 2 つの回避策があります (アプリケーション全体で 1 つのクライアントインスタンスを既に使用している場合)。

Azure Virtual Machines 仮想ネットワークのサブネットに Azure Cosmos DB サービスエンドポイントを追加します。詳細については、Azure 仮想ネットワークサービスエンドポイントに関するページを参照してください。

サービスエンドポイントが有効になると、要求はパブリック IP から Azure Cosmos DB に送信されなくなります。代わりに、仮想ネットワークとサブネット ID が送信されます。この変更により、パブリック IP のみが許可された場合はファイアウォールドロップが発生することがあります。ファイアウォールを使用している場合、サービスエンドポイントを有効にするときに、Virtual Network ACL を使用してファイアウォールにサブネットを追加します。
Azure VM にパブリック IP を割り当てます。

長いネットワーク待ち時間

待機時間のトラブルシューティングの詳細については、待機時間トラブルシューティングガイドを参照してください。

プロキシの認証エラー

HTTP 407 として表示されるエラーが発生する場合:

Response status code does not indicate success: ProxyAuthenticationRequired (407);

このエラーは SDK によって生成されるものでも、Azure Cosmos DB サービスから発生するものでもありません。これは、ネットワーク構成に関連するエラーです。ネットワーク構成のプロキシで、必要なプロキシ認証が不足している可能性が高いです。プロキシを使用する予定がない場合は、ネットワークチームにお問い合わせください。プロキシを使用 "する" 場合は、クライアントインスタンスの作成時に CosmosClientOptions.WebProxy で適切な WebProxy 構成を設定していることを確認してください。

一般的なクエリの問題

クエリメトリックは、クエリがほとんどの時間を費やしている箇所を特定する場合に役立ちます。クエリメトリックから、バックエンドとクライアントでどれだけの時間が費やされているかを確認できます。詳細については、クエリパフォーマンスガイドを参照してください。

エラー Unable to load DLL 'Microsoft.Azure.Cosmos.ServiceInterop.dll' or one of its dependencies: が発生したとき、Windows を使用している場合、最新の Windows バージョンにアップグレードしてください。

次のステップ

.NET SDK のパフォーマンスガイドラインを確認する
.NET SDK のベストプラクティスを確認する

次の方法で共有