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 エラーが発生した場所に関する次の情報が含まれています。
    • LinkErrorContext: 送信リンクまたは受信リンクのいずれかで発生するエラー。
    • SessionErrorContext: セッションで発生するエラー。
    • AmqpErrorContext: 接続で発生するエラーまたは、一般的な AMQP エラー。

一般的に発生する例外

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

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

アクセス許可の問題

amqp:unauthorized-access の AmqpErrorCondition がある AmqpException とは、指定済み資格情報が Event Hubs でアクション (送受信) の実行を許可されていないことを示します。 この問題を解決するには、次のタスクを実行します。

その他の解決策については、「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 で使用できる IoT に変換する方法について説明します。

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

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

従来の 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. 「Log4J 2 に必要な依存性」セクションの [logging sample pom.xml] からの依存性を使用して pom.xml に依存性を追加します。
  2. log4j2.xml を src/main/resources フォルダーに追加します。

Logback を構成する

Logback を構成するには、次の手順を実行します。

  1. 「Logback に必要な依存性」セクションの [logging sample pom.xml] からの依存性を使用して pom.xml に依存性を追加します。
  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 からの TRACE レベルの出力を proton-trace.log ファイルに記録します。

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 つとして、詳細度の変更が挙げられます。 別の方法として、com.azure.messaging.eventhubs や com.azure.core.amqp などのロガー名パッケージからログを除外するフィルターを追加します。 例については、「Log4J 2 の構成」および「logback の構成」セクションの 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 リポジトリに問題を提出することをお勧めします。