如何使用資源記錄進行疑難排解

文章
04/10/2024

本操作說明指南提供 Azure Web PubSub 資源記錄的概觀，以及使用記錄對特定問題進行疑難排解的一些秘訣。記錄可用於問題識別、連線追蹤、訊息追蹤、HTTP 要求追蹤和分析。

什麼是資源記錄？

資源記錄有三種類型：連線、訊息和 HTTP 要求。

連線記錄提供 Azure Web PubSub 中樞連線的詳細資訊。例如，基本資訊 (使用者識別碼、連線識別碼等等) 和事件資訊 (連線、中斷連線等等)。
訊息記錄提供透過 Azure Web PubSub 服務所接收和傳送的 Azure Web PubSub 中樞訊息追蹤資訊。例如，訊息的追蹤識別碼和訊息類型。
HTTP 要求記錄提供 Azure Web PubSub 服務的 HTTP 要求追蹤資訊。例如，HTTP 方法和狀態碼。一般而言，系統會在 HTTP 要求抵達或離開服務時加以記錄。

使用即時追蹤工具來擷取資源記錄

Azure Web PubSub 服務即時追蹤工具能夠即時收集資源記錄，這有助於對開發環境中的問題進行疑難排解。即時追蹤工具可以擷取連線記錄、訊息記錄和 HTTP 要求記錄。

注意

以下是使用即時追蹤工具的注意事項：

即時追蹤工具所擷取的即時資源記錄將會按訊息數 (輸出流量) 計費。
即時追蹤工具目前不支援 Microsoft Entra 授權。您必須啟用存取金鑰，才能使用即時追蹤。在 [設定] 下方，選取 [金鑰]，然後啟用 [存取金鑰]。
Azure Web PubSub 服務免費層執行個體的每日限制為 20，000 則訊息 (輸出流量)。即時追蹤可能會讓您不小心就達到每日上限。

啟動即時追蹤工具

注意

啟用存取金鑰時，您將使用存取權杖來驗證即時追蹤工具。否則，您將使用 Microsoft Entra ID 來驗證即時追蹤工具。您可以在 Azure 入口網站的 SignalR Service 金鑰頁面中檢查是否啟用存取金鑰。

啟用存取金鑰的步驟

移至 Azure 入口網站和 [SignalR Service] 頁面。
在左側功能表的 [監視] 底下，選取 [即時追蹤設定]。
選取 [啟用即時追蹤]。
選取 [儲存] 按鈕。變更需要一些時間才會生效。
更新完成時，請選取 [開啟即時追蹤工具]。

停用存取金鑰的步驟

將即時追蹤工具 API 權限指派給自己

移至 Azure 入口網站和 [SignalR Service] 頁面。
選取 [存取控制 (IAM)]。
在新頁面中，按一下 [+新增]，然後按一下 [角色指派]。
在新頁面中，將焦點放在 [工作職能角色] 索引標籤上，選取 [SignalR Service 擁有者] 角色，然後按 [下一步]。
在 [成員] 頁面中，按一下 [+選取成員]。
在新面板中，搜尋並選取成員，然後按一下 [選取]。
按一下 [檢閱 + 指派]，然後等候完成通知。

造訪即時追蹤工具

移至 Azure 入口網站和 [SignalR Service] 頁面。
在左側功能表的 [監視] 底下，選取 [即時追蹤設定]。
選取 [啟用即時追蹤]。
選取 [儲存] 按鈕。變更需要一些時間才會生效。
更新完成時，請選取 [開啟即時追蹤工具]。

即時追蹤工具將會彈出 Microsoft 登入視窗。如果沒有視窗彈出，請檢查並允許瀏覽器中的快顯視窗。
等候狀態列中顯示 [就緒]。

擷取資源記錄

即時追蹤工具提供的功能可協助您擷取資源記錄以進行疑難排解。

擷取：開始從 Azure Web PubSub 擷取即時資源記錄。
清除：清除所擷取的即時資源記錄。
記錄篩選：即時追蹤工具可讓您使用一個特定的關鍵字來篩選擷取的即時資源記錄。常見的分隔符號 (例如空格、逗號、分號等) 會被視為關鍵字的一部分。
狀態：狀態會顯示即時追蹤工具是否與特定執行個體連線或中斷連線。

Screenshot of capturing resource logs with live trace tool.

即時追蹤工具所擷取的即時資源記錄包含疑難排解的詳細資訊。

名稱	描述
Time	記錄事件時間
記錄層級	記錄事件層級，可以是 [追蹤 \| 偵錯 \| 資訊 \| 警告 \| 錯誤]
事件名稱	事件的作業名稱
訊息	事件的詳細訊息
例外狀況	Azure Web PubSub 服務的執行階段例外狀況
中樞	使用者定義的中樞名稱
連線識別碼	連線的身分識別
使用者識別碼	使用者身分識別
IP	用戶端 IP 位址
路由範本	API 的路由範本
HTTP 方法	HTTP 方法 (POST/GET/PUT/DELETE)
URL	統一資源定位器
追蹤識別碼	叫用的唯一識別碼
狀態碼	HTTP 回應碼
期間	接收要求和處理要求之間的持續時間
標頭	用戶端和伺服器透過 HTTP 要求或回應傳遞的其他資訊

使用 Azure 監視器擷取資源記錄

如何啟用資源記錄

Azure Web PubSub 目前支援整合 Azure 儲存體。

前往 Azure 入口網站。
在 Azure Web PubSub 服務執行個體的 [診斷設定] 頁面上，選取 [+ 新增診斷設定]。
在 [診斷設定名稱] 中，輸入設定名稱。
在 [類別詳細資料] 中，選取您需要的任何記錄類別。
在 [目的地詳細資料] 中，核取 [封存至儲存體帳戶]。
選取 [儲存] 以儲存診斷設定。

注意

儲存體帳戶應位於與 Azure Web PubSub 服務相同的區域中。

封存至 Azure 儲存體帳戶

記錄會儲存在 [診斷設定] 窗格中所設定的儲存體帳戶。會自動建立名為 insights-logs-<CATEGORY_NAME> 的容器來儲存資源記錄。在容器內，記錄會儲存在 resourceId=/SUBSCRIPTIONS/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/RESOURCEGROUPS/XXXX/PROVIDERS/MICROSOFT.SIGNALRSERVICE/SIGNALR/XXX/y=YYYY/m=MM/d=DD/h=HH/m=00/PT1H.json 檔案中。路徑是由 resource ID 與 Date Time 合併。記錄檔會依 hour 進行分割。分鐘值一律為 m=00。

所有記錄都會以「JavaScript 物件標記法」(JSON) 格式儲存。每個項目都具有字串欄位，這些欄位會使用下列小節所述的格式。

封存記錄 JSON 字串包括下表所列的元素：

格式

名稱	描述
time	記錄事件時間
level	記錄事件層級
resourceId	Azure SignalR Service 的資源識別碼
location	Azure SignalR Service 的位置
category	記錄事件的類別
operationName	事件的作業名稱
callerIpAddress	伺服器或用戶端的 IP 位址
內容	與這個記錄事件相關的詳細屬性。如需詳細資料，請參閱以下的屬性資料表

屬性資料表

名稱	描述
collection	記錄事件的集合。允許值為：`Connection`、`Authorization` 和 `Throttling`
connectionId	連線的身分識別
userId	使用者的身分識別
message	記錄事件的詳細訊息
集線器	使用者定義的中樞名稱
routeTemplate	API 的路由範本
httpMethod	HTTP 方法 (POST/GET/PUT/DELETE)
URL	統一資源定位器
traceId	叫用的唯一識別碼
statusCode	HTTP 回應碼
duration	收到和處理要求之間的持續時間
標題	用戶端和伺服器透過 HTTP 要求或回應所傳遞的其他資訊

下列程式碼是封存記錄 JSON 字串的範例：

{
  "properties": {
    "message": "Connection started",
    "collection": "Connection",
    "connectionId": "LW61bMG2VQLIMYIVBMmyXgb3c418200",
    "userId": null
  },
  "operationName": "ConnectionStarted",
  "category": "ConnectivityLogs",
  "level": "Informational",
  "callerIpAddress": "167.220.255.79",
  "resourceId": "/SUBSCRIPTIONS/XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX/RESOURCEGROUPS/MYGROUP/PROVIDERS/MICROSOFT.SIGNALRSERVICE/WEBPUBSUB/MYWEBPUBSUB",
  "time": "2021-09-17T05:25:05Z",
  "location": "westus"
}

封存至 Azure Log Analytics

若要將記錄傳送至 Log Analytics 工作區：

在 [診斷設定] 頁面的 [目的地詳細資料] 下方，選取 [**傳送至 Log Analytics 工作區]。
選取您要使用的 [訂用帳戶]。
選取要作為記錄目的地的 Log Analytics 工作區。

若要檢視資源記錄，請遵循下列步驟：

在目標 Log Analytics 中，選取 Logs。
輸入 WebPubSubConnectivity、WebPubSubMessaging 或 WebPubSubHttpRequest，然後選取要查詢記錄的時間範圍。如需進階查詢，請參閱開始使用 Azure 監視器中的 Log Analytics。

若要使用 SignalR 服務的範例查詢，請遵循下列步驟。

在目標 Log Analytics 中，選取 Logs。
選取 Queries，以開啟查詢總管。
選取 Resource type，以將範例查詢分組在資源類型中。
選取 Run 以執行指令碼。

封存記錄資料行包括下表所列的元素。

名稱	描述
TimeGenerated	記錄事件時間
集合	記錄事件的集合。允許值為：`Connection`、`Authorization` 和 `Throttling`
OperationName	事件的作業名稱
Location	Azure SignalR Service 的位置
層級	記錄事件層級
CallerIpAddress	伺服器/用戶端的 IP 位址
訊息	記錄事件的詳細訊息
UserId	使用者的身分識別
ConnectionId	連線的身分識別
ConnectionType	連線的類型。允許值為：`Server` \| `Client`。 `Server`：來自伺服器端的連線；`Client`：來自用戶端的連線
TransportType	連線的傳輸類型。允許值為：`Websockets` \| `ServerSentEvents` \| `LongPolling`

使用資源記錄進行疑難排解

如果您發現連線數目有非預期的變更，無論是增加或減少，都可以利用資源記錄對問題進行疑難排解。一般問題通常是關於連線發生意外的連線數量變更、連線達到連線限制，以及授權失敗。

連線數目發生未預期的變更

未預期的連線中斷

如果連線中斷，資源記錄會在 operationName 中使用 ConnectionAborted 或 ConnectionEnded 記錄連線中斷事件。

ConnectionAborted 與 ConnectionEnded 之間的差異在於，ConnectionEnded 是用戶端或伺服器端所觸發的預期中斷連線。 ConnectionAborted 通常是意外的連線中斷事件，系統會在 message 中提供連線中斷的原因。

中止原因會在下表中列出：

原因	描述
連線計數達到限制	連線計數達到您目前價格區間的限制。請考慮調整服務單位規模
服務重新載入、重新連線	Azure Web PubSub 服務正在重新載入。您必須實作自己的重新連線機制，或手動重新連線至 Azure Web PubSub 服務
內部伺服器暫時性錯誤	Azure Web PubSub 服務發生暫時性錯誤，應該會自動復原

非預期的連線數目增加

當用戶端連線數目意外增加時，您第一件要做的事就是篩選掉多餘的連線。請將唯一測試使用者識別碼新增至測試用戶端連線。然後檢查資源記錄；如果您看到多個用戶端連線具有相同的測試使用者識別碼或 IP，則用戶端可能會建立較預期更多的連線。請檢查您的用戶端程式代碼，以尋找額外連線的來源。

授權失敗

如果您收到 401 未經授權傳回用戶端要求，請檢查您的資源記錄。如果您發現 Failed to validate audience. Expected Audiences: <valid audience>. Actual Audiences: <actual audience>，這表示您存取權杖中的所有對象都無效。請嘗試使用記錄中建議的有效對象。

節流

如果您發現無法建立 Azure Web PubSub 服務的用戶端連線，請檢查您的資源記錄。如果您在資源記錄中看到 Connection count reaches limit，您已建立太多 Azure Web PubSub 服務連線，且已達到連線計數限制。請考慮調整擴大您的 Azure Web PubSub 服務執行個體。如果您在資源記錄中看到 Message count reaches limit 並使用免費層，表示您已用盡訊息配額。如果您想要傳送更多訊息，請考慮將 Azure Web PubSub 服務執行個體變更為標準層。如需詳細資訊，請參閱 Azure Web PubSub 服務價格。

分享方式：

如何使用資源記錄進行疑難排解

什麼是資源記錄？

使用即時追蹤工具來擷取資源記錄