針對 Azure 事件中樞進行疑難解答

本文將介紹如何排解 Azure 事件中樞 的故障，包括 Event Hubs 函式庫中憑證類型的常見錯誤及解決方法。 除了適用於事件中心使用案例的一般疑難排解技術和指引之外，下列文章還涵蓋事件中心函式庫的特定功能：

本文的其餘部分涵蓋適用於事件中樞連結庫所有使用者的一般疑難解答技術和指引。

處理事件中樞例外狀況

所有的事件中樞例外狀況都會被包裹在 AmqpException中。 這些例外狀況通常會有一個基礎 AMQP 錯誤碼，指定是否應該重試錯誤。 針對可重試的錯誤（也就是 amqp:connection:forced 或 amqp:link:detach-forced），用戶端連結庫會根據具現化用戶端時指定的重試選項，嘗試從這些錯誤中復原。 若要設定重試選項，請遵循範例 將事件發佈至特定分割區。 如果錯誤無法重試，則需要解決一些設定問題。

解決AMQP例外狀況所代表之特定例外狀況的建議方式，是遵循 事件中樞傳訊例外狀況 指引。

在例外狀況訊息中尋找相關信息

AmqpException 包含下列三個字段，其中描述錯誤：

  • getErrorCondition：基礎 AMQP 錯誤。 如需錯誤的描述，請參閱 AmqpErrorCondition Enum 文件或 OASIS AMQP 1.0 規格。
  • isTransient：指出是否可能嘗試執行相同作業的值。 當錯誤為暫時性時，SDK 用戶端會套用重試原則。
  • getErrorContext：包含 AMQP 錯誤產生位置的下列資訊：

常見的事件中心例外

amqp：connection：forced 和 amqp：link：detach-forced

當事件中樞的連線閑置時，服務會在一段時間后中斷用戶端連線。 這種行為不是問題，因為當請求服務操作時，客戶端會重新建立連線。 如需詳細資訊，請參閱 Azure 服務總線中的 AMQP 錯誤。

解決 Event Hubs 權限問題

具有 AmqpException 的 amqp:unauthorized-access 表示所提供的認證不允許使用事件中樞執行動作（接收或傳送）。 若要解決此問題，請嘗試下列工作：

如需其他可能的解決方案，請參閱 針對事件中樞的驗證和授權問題進行疑難解答。

解決事件中心連線問題

連接到服務時超時

若要解決逾時問題，請嘗試下列操作：

TLS/SSL 交握失敗

此錯誤可能發生在使用攔截代理時。 為了驗證，請在你的主機環境中測試，並且關閉代理。

套接字資源耗盡錯誤

把活動中心的客戶當作單一客戶來對待。 在應用程式的整個生命週期內建立並使用單一實例。 這項建議很重要，因為每個客戶端類型都會管理其連線。 當你建立新的 Event Hubs 客戶端時，你會建立一個新的 AMQP 連線，該連線會使用一個套接字。 此外，客戶端必須繼承自 java.io.Closeable，因此您的應用程式必須負責在結束使用客戶端時呼叫 close()。

若要在建立多個用戶端時使用相同的 AMQP 連線，請使用 EventHubClientBuilder.shareConnection() 旗標、保留該 EventHubClientBuilder 的參考，並從相同的建構器執行個體建立新的用戶端。

使用IoT連接字串進行連線

因為轉譯連接字串需要查詢IoT中樞服務，所以事件中樞用戶端連結庫無法直接使用它。 IoTConnectionString.java 範例說明如何查詢IoT中樞，將IoT連接字串轉譯成可與事件中樞搭配使用的連接字串。

如需詳細資訊，請參閱下列文章：

無法將元件新增至連接字串

舊有的 Event Hubs 用戶端允許你在從 Azure 入口取得的 連接字串 中新增元件。 舊版用戶端 位於 com.microsoft.azure：azure：azure-eventhubs 和 com.microsoft.azure：azure-eventhubs-eph套件中。 目前的世代僅支援 Azure 入口網站所發佈的表單中的連接字串。

新增參數 "TransportType=AmqpWebSockets"

若要使用 Web 套接字，請參閱 PublishEventsWithSocketsAndProxy.java 範例。

新增 “Authentication=Managed Identity”

若要使用受控識別進行驗證，請參閱範例 PublishEventsWithAzureIdentity.java。

如需進一步了解 Azure.Identity 程式庫，請參閱 驗證與 Azure SDK 部落格文章。

啟用並設定事件中心的日誌功能

適用於 Java 的 Azure SDK 提供一致的記錄案例，可協助針對應用程式錯誤進行疑難解答，並協助加速解決。 你產生的日誌記錄應用程式在進入終端狀態前的流程，幫助找出根本問題。 如需記錄的指引，請參閱 在 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 中新增相依性。
  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” 檔案

下列組態檔會將 TRACE 層級輸出從 Proton-J 至 記錄到 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

減少砍伐

減少日誌記錄的其中一種方式是變更詳盡性。 另一種方式是新增篩選器，以排除來自記錄器名稱套件的日誌，例如 com.azure.messaging.eventhubs 或 com.azure.core.amqp。 如需範例，請參閱 設定Log4J 2 和 設定logback 小節中的 XML 檔案。

當您提交 Bug 時，下列套件中類別的記錄訊息很有趣：

  • com.azure.core.amqp.implementation
  • com.azure.core.amqp.implementation.handler
    • 例外狀況是您可以忽略 onDelivery中的 ReceiveLinkHandler 訊息。
  • com.azure.messaging.eventhubs.implementation

後續步驟

如果本文的故障排除指引無法幫助你解決使用Azure SDK Java客戶端函式庫的問題，請在Java GitHub儲存庫的Azure SDK中提出問題。

  • Last updated on