次の方法で共有

Azure Event Hubs のトラブルシューティング

  • [アーティクル]

この記事では、エラー調査の手法、Event Hubs ライブラリの資格情報の種類に関する一般的なエラー、およびこれらのエラーを解決するための軽減手順について説明します。 Event Hubs のユース ケースに関係なく適用される一般的なトラブルシューティング手法とガイダンスに加えて、次の記事では Event Hubs ライブラリの特定の機能について説明します。

この記事の残りの部分では、Event Hubs ライブラリのすべてのユーザーに適用される一般的なトラブルシューティング手法とガイダンスについて説明します。

Event Hubs の例外を処理する

すべての Event Hubs 例外は、AmqpExceptionでラップされます。 多くの場合、これらの例外には、エラーを再試行するかどうかを指定する基になる AMQP エラー コードがあります。 再試行可能なエラー (つまり、amqp:connection:forced または amqp:link:detach-forced) の場合、クライアント ライブラリは、クライアントのインスタンス化時に指定された再試行オプションに基づいて、これらのエラーからの回復を試みます。 再試行オプションを構成するには、特定のパーティションにイベントを発行 サンプルに従います。 エラーが解決できない場合は、いくつかの構成の問題を解決する必要があります。

AMQP 例外が表す特定の例外を解決するには、Event Hubs メッセージング例外 ガイダンスに従うことをお勧めします。

例外メッセージで関連情報を検索する

AmqpException には、エラーを説明する次の 3 つのフィールドが含まれています。

  • getErrorCondition: 基になる AMQP エラー。 エラーの詳細については、AmqpErrorCondition Enum のドキュメントまたは OASIS AMQP 1.0 仕様を参照してください。
  • isTransient: 同じ操作を実行できるかどうかを示す値。 SDK クライアントは、エラーが一時的な場合に再試行ポリシーを適用します。
  • getErrorContext: AMQP エラーが発生した場所に関する次の情報が含まれています。

一般的に発生する例外

amqp:connection:forced and amqp:link:detach-forced

Event Hubs への接続がアイドル状態になると、サービスはしばらくしてからクライアントを切断します。 サービス操作が要求されたときにクライアントが接続を再確立するため、この問題は問題ではありません。 詳細については、Azure Service Busでの AMQP エラーの に関するページを参照してください。

アクセス許可の問題

AmqpException における AmqpErrorCondition が amqp:unauthorized-access である場合、提供された資格情報では Event Hubs でアクション（受信または送信）を実行できないことを意味します。 この問題を解決するには、次のタスクを試してください。

  • 正しい接続文字列があることを再確認します。 詳細については、「Event Hubs の接続文字列の取得」を参照してください。
  • Shared Access Signature (SAS) トークンが正しく生成されていることを確認します。 詳細については、「Shared Access Signaturesを使用した Event Hubs リソースへのアクセスの承認」を参照してください。

その他の解決策については、「Event Hubsでの認証と承認の問題のトラブルシューティング」を参照してください。

接続の問題

サービスに接続するときのタイムアウト

タイムアウトの問題を解決するには、次のタスクを試してください。

  • クライアントの作成時に指定された接続文字列または完全修飾ドメイン名が正しいことを確認します。 詳細については、「Event Hubs の接続文字列の取得」を参照してください。
  • ホスト環境のファイアウォールとポートのアクセス許可を確認し、AMQP ポート 5671 と 5762 が開かれていることを確認します。
    • エンドポイントがファイアウォール経由で許可されていることを確認します。
  • ポート 443 で接続する WebSocket を使用してみてください。 詳細については、PublishEventsWithWebSocketsAndProxy.java サンプルを参照してください。
  • ネットワークが特定の IP アドレスをブロックしているかどうかを確認します。 詳細については、「許可する必要がある IP アドレス を参照してください。
  • 該当する場合は、プロキシの構成を確認します。 詳細については、PublishEventsWithWebSocketsAndProxy.java サンプルを参照してください。
  • ネットワーク接続のトラブルシューティングの詳細については、「接続の問題のトラブルシューティング - Azure Event Hubs」を参照してください。

TLS/SSL ハンドシェイク エラー

このエラーは、インターセプト プロキシが使用されている場合に発生する可能性があります。 確認するには、プロキシを無効にしてホスティング環境でテストすることをお勧めします。

ソケット不足エラー

アプリケーションでは、Event Hubs クライアントをシングルトンとして扱い、アプリケーションの有効期間を通じて 1 つのインスタンスを作成して使用することを好む必要があります。 クライアントの種類ごとに接続が管理されるため、この推奨事項は重要です。 新しい Event Hubs クライアントを作成すると、ソケットを使用する新しい AMQP 接続が作成されます。 さらに、クライアントが java.io.Closeableから継承することが不可欠であるため、クライアントの使用が完了したときにアプリケーションが close() を呼び出す必要があります。

複数のクライアントを作成するときに同じ AMQP 接続を使用するには、EventHubClientBuilder.shareConnection() フラグを使用し、その EventHubClientBuilderへの参照を保持し、同じビルダー インスタンスから新しいクライアントを作成します。

IoT 接続文字列を使用して接続する

接続文字列を変換するには IoT Hub サービスに対してクエリを実行する必要があるため、Event Hubs クライアント ライブラリで直接使用することはできません。 IoTConnectionString.java サンプルでは、IoT Hub にクエリを実行して、IoT 接続文字列を Event Hubs で使用できる接続文字列に変換する方法について説明します。

詳細については、次の記事を参照してください。

接続文字列にコンポーネントを追加できない

従来の Event Hubs クライアントを使用すると、お客様は Azure portal から取得した接続文字列にコンポーネントを追加できます。 レガシ クライアントは、パッケージ com.microsoft.azure:azure-eventhubs と com.microsoft.azure:azure-eventhubs-ephに含まれています。 現在の世代では、Azure portal によって発行された形式でのみ接続文字列がサポートされます。

"TransportType=AmqpWebSockets" を追加する

Web ソケットを使用するには、PublishEventsWithSocketsAndProxy.java サンプルを参照してください。

「Authentication=Managed Identity」を追加します。

マネージド ID で認証するには、サンプルの PublishEventsWithAzureIdentity.javaを参照してください。

Azure.Identity ライブラリの詳細については、認証と Azure SDK ブログ記事を参照してください。

ログ記録を有効にして構成する

Azure SDK for Java では、アプリケーション エラーのトラブルシューティングに役立ち、解決を迅速化するために役立つ一貫したログ記録のストーリーが提供されます。 生成されたログは、ルートの問題の特定に役立つターミナル状態に達する前に、アプリケーションのフローをキャプチャします。 ログ記録のガイダンスについては、「Azure SDK for Java でのログ記録の構成」および「トラブルシューティングの概要を参照してください。

ログ記録を有効にするだけでなく、ログ レベルを VERBOSE または DEBUG に設定すると、ライブラリの状態に関する分析情報が得られます。 次のセクションでは、詳細ログが有効になっている場合の過剰なメッセージを減らすための log4j2 と logback の構成の例を示します。

Log4J 2 の構成

Log4J 2 を構成するには、次の手順に従います。

  1. 「Log4j2 に必要な依存関係」セクションの ログサンプル pom.xmlの依存関係を使用して、pom.xml に依存関係を追加します。
  2. log4j2.xml を src/main/resources フォルダーに追加します。

Logback を構成する

ログバックを構成するには、次の手順に従います。

  1. ログ サンプル pom.xmlの依存関係を使用して、pom.xml の [Logback に必要な依存関係] セクションに依存関係を追加します。
  2. logback.xml を src/main/resources フォルダーに追加します。

AMQP トランスポート ログを有効にする

問題を診断するのにクライアント ログを有効にするだけでは不十分な場合は、基になる AMQP ライブラリ (Qpid Proton-Jファイルへのログ記録を有効にできます。 Qpid Proton-J では java.util.loggingが使用されます。 ログ記録を有効にするには、次のセクションに示す内容を含む構成ファイルを作成します。 または、proton.trace.level=ALL と、java.util.logging.Handler 実装に必要な構成オプションを設定します。 実装クラスとそのオプションについては、Java 8 SDK ドキュメント java.util.logging をパッケージ化するを参照してください。

AMQP トランスポート フレームをトレースするには、PN_TRACE_FRM=1 環境変数を設定します。

サンプル "logging.properties" ファイル

次の構成ファイルは、Proton-J から proton-trace.log ファイルへの TRACE レベルの出力をログに記録します。

handlers=java.util.logging.FileHandler
.level=OFF
proton.trace.level=ALL
java.util.logging.FileHandler.level=ALL
java.util.logging.FileHandler.pattern=proton-trace.log
java.util.logging.FileHandler.formatter=java.util.logging.SimpleFormatter
java.util.logging.SimpleFormatter.format=[%1$tF %1$tr] %3$s %4$s: %5$s %n

ログ記録の削減

ログ記録を減らす 1 つの方法は、詳細度を変更する方法です。 もう 1 つの方法は、com.azure.messaging.eventhubs や com.azure.core.amqpなどのロガー名パッケージからログを除外するフィルターを追加することです。 例については、「Log4J 2 の構成」および「ログバック の構成」セクション XML ファイルを参照してください。

バグを送信すると、次のパッケージのクラスからのログ メッセージが興味深いものになります。

  • com.azure.core.amqp.implementation
  • com.azure.core.amqp.implementation.handler
    • 例外は、ReceiveLinkHandlerの onDelivery メッセージを無視できることです。
  • com.azure.messaging.eventhubs.implementation

次の手順

この記事のトラブルシューティング ガイダンスが、Azure SDK for Java クライアント ライブラリを使用するときに問題を解決するのに役立たない場合は、Azure SDK for Java GitHub リポジトリに 問題を報告 することをお勧めします。