NoSQL 用 API アカウントで Azure Cosmos DB Python SDK を使用する場合の問題のトラブルシューティング

適用対象: NoSQL

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

次の一覧から開始します。

• この記事の一般的な問題と対処法のセクションを確認します。
• Azure Cosmos DB 中央リポジトリにある Python SDK を参照してください。これは、GitHub のオープン ソースとして利用可能です。 アクティブに監視されている問題セクションがあります。 回避策が既に提出済みの同様の問題がないか確認します。 役立つヒントの 1 つは、*Cosmos* タグで問題をフィルター処理することです。
• Azure Cosmos DB Python SDK のパフォーマンスに関するヒントを確認し、推奨される方法に従います。
• この記事の残りの部分を読みます。解決策が見つからない場合は、 GitHub の問題を提出します。 GitHub の問題にタグを追加するオプションがある場合は、*Cosmos* タグを追加します。

診断のログと取得

このライブラリでは、診断のログ記録に標準のログ ライブラリを使用します。 HTTP セッションに関する基本的な情報 (URL、ヘッダーなど) は、INFO レベルでログされます。

要求と応答の本文や編集されていないヘッダーなどの詳細な DEBUG レベルのログは、logging_enable 引数を使ってクライアントで有効にできます。

import sys
import logging
from azure.cosmos import CosmosClient

# Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

# This client will log detailed information about its HTTP sessions, at DEBUG level
client = CosmosClient(URL, credential=KEY, logging_enable=True)

同様に、logging_enable は、詳細なログ記録がクライアントで有効になっていない場合でも、1 回の操作のために有効にすることができます。

database = client.create_database(DATABASE_NAME, logging_enable=True)

または、使用するロガーを logger 引数に渡すことによって azure コアの HttpLoggingPolicy から拡張される、CosmosHttpLoggingPolicy を使用してログを記録することもできます。 既定では、HttpLoggingPolicy からの動作が使用されます。 enable_diagnostics_logging 引数を渡すと、CosmosHttpLoggingPolicy が有効になり、Cosmos に関する問題のデバッグに関連する追加情報が返されます。

import logging
from azure.cosmos import CosmosClient

#Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)

# Configure a file output
handler = logging.FileHandler(filename="azure")
logger.addHandler(handler)

# This client will log diagnostic information from the HTTP session by using the CosmosHttpLoggingPolicy.
# Since we passed in the logger to the client, it will log information on every request.
client = CosmosClient(URL, credential=KEY, logger=logger, enable_diagnostics_logging=True)

同様に、ロガーを単一の要求に渡すことで、1 回の操作に対してログ記録を有効にできます。 ただし、CosmosHttpLoggingPolicy を使用して追加情報を取得する場合は、クライアント コンストラクターで enable_diagnostics_logging 引数を渡す必要があります。

# This example enables the `CosmosHttpLoggingPolicy` and uses it with the `logger` passed in to the `create_database` request.
client = CosmosClient(URL, credential=KEY, enable_diagnostics_logging=True)
database = client.create_database(DATABASE_NAME, logger=logger)

再試行の設計

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

一般的な問題と対処法

一般的な推奨事項

パフォーマンスを最大限高めるためのヒントを示します。

• アプリが Azure Cosmos DB アカウントと同じリージョンで実行されていることを確認します。
• アプリが実行されているホストの CPU 使用率を確認します。 CPU 使用率が 50% 以上の場合は、より高度な構成のホスト上でアプリを実行します。 また、より多数のマシンに負荷を分散することもできます。
  • Azure Kubernetes Service でアプリケーションを実行している場合は、Azure Monitor を使用して CPU 使用率を監視することができます。

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

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

接続の帯域幅調整

接続の帯域幅調整は、[ホスト マシンの接続制限]、または [Azure SNAT (PAT) ポート不足] のいずれかが原因で発生します。

ホスト マシンの接続制限

一部の Linux システム (Red Hat など) では、開くファイルの最大数に上限があります。 Linux のソケットはファイルとして実装されるため、この数は接続の合計数も制限します。 次のコマンドを実行します。

ulimit -a

開くことができる最大ファイル数 ("nofile" で指定) は、接続プール サイズの 2 倍以上にする必要があります。 詳細については、Azure Cosmos DB Python SDK のパフォーマンスに関するヒントを参照してください。

Azure SNAT (PAT) ポート不足

パブリック IP アドレスを使わずにアプリを Azure Virtual Machines にデプロイした場合、既定では Azure SNAT ポートによって VM 外の任意のエンドポイントへの接続が確立されます。 VM から Azure Cosmos DB エンドポイントへの許可される接続の数は、Azure SNAT 構成によって制限されます。

Azure SNAT ポートが使用されるのは、VM がプライベート IP アドレスを持ち、VM からのプロセスが、パブリック IP アドレスに接続しようとしている場合に限られます。 Azure SNAT の制限を回避するには次の 2 つの回避策があります。

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

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

• Azure VM にパブリック IP を割り当てます。

サービスに到達できない - ファイアウォール

azure.core.exceptions.ServiceRequestError: は、SDK がサービスに到達できないことを示します。 「ホスト マシンの接続制限」に従ってください。

Azure Cosmos DB エミュレーターへの接続の失敗

Azure Cosmos DB エミュレーターの HTTPS 証明書が自己署名されています。 Python SDK でエミュレーターを動作させるには、エミュレーター証明書をインポートします。 詳細については、Azure Cosmos DB エミュレーター証明書のエクスポートに関するページを参照してください。

HTTP プロキシ

HTTP プロキシを使用する場合は、SDK ConnectionPolicy で構成されている接続の数をサポートできることを確認します。 できない場合、接続の問題が発生します。

一般的なクエリの問題

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

次のステップ

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