收集並解譯錯誤數據
重要
這是 Azure Sphere （舊版） 檔。 Azure Sphere（舊版）將於 2027 年 9 月 27 日淘汰，且使用者此時必須移轉至 Azure Sphere（整合式）。 使用位於 TOC 上方的版本選取器來檢視 Azure Sphere （整合式） 檔。
錯誤和事件數據會每天上傳至 Azure Sphere 安全性服務。 任何有權存取特定租用戶的人員，都可以下載該租用戶的數據。 報表涵蓋租使用者中的所有裝置。
每個報表最多包含1,000個事件或14天的數據，只要先到達。 數據可以寫入檔案或管線傳送至腳本或應用程式。 CLI 只能傳回 1,000 個事件。 使用 Azure Sphere 公用 API 來指定頁面上傳回的事件數目上限。
您可以透過下列方式下載有關錯誤和其他影響裝置事件的資料：
使用 azsphere tenant download-error-report 命令。 下載 CSV 檔案，其中包含目前租用戶內裝置所報告之錯誤和事件的相關信息。
使用 Azure Sphere 公用 API 進行錯誤報告。 API 端點會傳回您可以根據需求剖析的 JSON 物件。
不會從 RTApps 收集任何錯誤報告數據。 如果您想要記錄來自 RTApps 的錯誤，您必須實作核心間通訊，以將來自 RTApps 的錯誤傳達至高階應用程式，以便從中將錯誤數據記錄到網路服務。 如需詳細資訊，請參閱 與高階應用程式 通訊和 與即時可用的應用程式 通訊。
可用的數據類型
針對每個錯誤或事件傳回的數據包含下列專案：
| 資料 | 描述 |
|---|---|
| 裝置識別碼 | 遇到事件的裝置標識碼。 |
| 事件類型 | 事件已規劃或非計劃性。 操作系統和應用程式更新會被視為計劃性事件，而錯誤則是非計劃性事件。 |
| Event Class | 遇到事件的軟體元件：OS 或應用程式。 |
| 事件計數 | 事件在以 StartTime 和 EndTime 分隔的期間內發生的次數。 |
| 描述 | 事件相關資訊。 此欄位是泛型欄位，會根據事件及其來源而有所不同。 對於應用程式，它可能包含結束代碼、訊號狀態和訊號代碼，但不會修正字段的確切內容。 這包含事件的相關信息，且來自時間範圍中第一次出現的事件。 |
| 開始時間 | 事件窗口開始的日期和時間（以 UTC 為單位）。 |
| 結束時間 | 事件窗口結束的日期和時間（UTC）。 |
[開始時間] 和 [結束時間] 會定義匯總事件數據的時間範圍。 任何匯總事件群組的視窗最多可以 24 小時，而且每個時間範圍的最大次數為 8 次。
應用程式事件
應用程式事件包括雲端載入的應用程式更新，以及當機、結束，以及其他類型的應用程式失敗。
應用程式更新是計劃性事件。 針對 AppUpdate 事件，[描述] 欄位包含 AppUpdate。
應用程式當機、結束、啟動失敗和類似的事件都是非計劃性事件。 對於非計劃性事件，[描述] 字段的內容取決於遇到事件的應用程式。 下表列出可能存在於非計劃事件 [描述] 欄位中的欄位。
| 資料 | 描述 |
|---|---|
| exit_status或exit_code | 應用程式所報告的結束狀態或程序代碼。 |
| signal_status | 整數，描述OS所傳回之當機的高階原因。 您可以在 Man 7 檔或其他 Linux 資源中找到狀態清單。 |
| signal_code | 整數，表示父訊號狀態內的詳細當機狀態。 如需詳細資訊，請參閱Man 7 檔或其他Linux資源。 |
| component_id | 當機的軟體元件 GUID。 |
| image_id | 在錯誤發生時執行的映像 GUID。 |
AppCrash 描述中的特定資訊取決於當機來源。 對於大部分當機，描述看起來會類似下列：
AppCrash (exit_status=11; signal_status=11; signal_code=3; component_id=685f13af-25a5-40b2-8dd8-8cbc253ecbd8; image_id=7053e7b3-d2bb-431f-8d3a-173f52db9675)
在某些情況下，當機會觸發其他錯誤數據，例如下列，以補充上一個範例中的數據：
AppCrash (pc=BEEED2EE; lr=BEEED2E5; sp=BEFFDE58; signo=11; errno=0; code=0; component_id=685f13af-25a5-40b2-8dd8-8cbc253ecbd8; pc_modulename+offset=appname+80000; lr_modulename+offset=app+100CC)
| 資料 | 描述 |
|---|---|
| pc | 程式計數器。 指向觸發當機的指令位址。 |
| lr | 連結快取器。 可能指向呼叫函式中的傳回位址。 |
| sp | 堆疊指標。 指向呼叫堆疊的頂端。 |
| signo | POSIX 訊號。 指出錯誤類型。 |
| errno | POSIX errno。 表示發生錯誤。 |
| code | 指出父訊號狀態內的詳細當機狀態。 |
| component_id | 當機的軟體元件 GUID。 |
| pc_modulename+offset | 模組的名稱，並位移到包含發生當機之程式代碼的模組中。 |
| lr_modulename+offset | 模組的名稱，並位移至可能是呼叫函式的模組。 |
解譯 AppCrashes
您可以在 signal_status 和 signal_code 中找到 AppCrash 的大部分資訊。 執行下列步驟:
- 使用 Man 7 檔進行signal_status，請先查看標示為「標準訊號的訊號編號」數據表。在 x86/ARM 數據行中，搜尋錯誤報告中
csv指派給signal_status的值。 找到之後，請記下最左邊數據行中對應的 Signal 名稱。 - 向上捲動至標示為「標準訊號」的數據表。比對先前決定的 Signal 名稱，並使用 資料表來收集有關訊號所指示的詳細資訊。
- 在signal_code的 Man 7 檔中，找到您先前找到的 Signal 名稱，找出對應的si_codes清單。
- 使用指派給錯誤報告
csv檔案中signal_code的值，判斷哪些程序代碼符合錯誤訊息。
例如，請考慮下列 AppCrash 描述：
AppCrash (exit_status=11; signal_status=11; signal_code=3; component_id=685f13af-25a5-40b2-8dd8-8cbc253ecbd8; image_id=7053e7b3-d2bb-431f-8d3a-173f52db9675)
使用 Man 7 檔，您可以探索下列 AppCrash 的其他資訊：
- 訊號會在 Signal man 頁面描述的第 10 節中描述。 值為 11 的signal_status對應至 SIGSEGV 訊號。
- SIGSEGV 表示發生無效的記憶體參考（這通常可以是 Null 指標）。
- SI_Codes會在每個signal_status的 SigAction 人頁面描述的第 3 節中說明。 雖然頁面並未列出每個si_code的索引編號，但您可以從索引 1 開始，從每個signal_status類別計算。 查看 SIGSEGV 的si_codes清單（從索引 1 開始），您可以看到第三個符合SEGV_BNDERR。
- SEGV_BNDERR表示發生失敗的位址系結檢查。
注意
常見的 AppCrash 包含 9 的signal_status值，也就是 SIGKILL 訊號，以及SEND_SIG_PRIV si_code。 此狀態表示操作系統因為超過其記憶體使用量限制而終止應用程式。 若要深入瞭解應用程式記憶體限制，請參閱 高階應用程式中的記憶體使用。
解譯 AppExits
當應用程式結束時沒有錯誤，signal_status和signal_code欄位不存在，而不是exit_status，描述包含結束代碼：
AppExit (exit_code=0; component_id=685f13af-25a5-40b2-8dd8-8cbc253ecbd8; image_id=0a7cc3a2-f7c2-4478-8b02-723c1c6a85cd)
AppExits 可能會因為許多原因而發生，例如應用程式更新、裝置未卸除，或使用關閉電源 API 等等。 請務必實 作結束代碼 ，以便深入瞭解 AppExit 的原因。
若要解譯 AppExits，請使用錯誤報告 [描述] 字段中exit_code值。 如果您的應用程式傳回結束代碼，您可以使用錯誤報告中exit_code的值來判斷錯誤發生的位置或時間。 使用此值，在應用程式程式代碼內搜尋，以查看哪個結束代碼訊息對應至錯誤報告中提供的值。 然後，尋找應用程式中哪一個函式傳回結束代碼訊息，以及其執行的原因。 藉由檢視 return 語句及其內容，您可以探索錯誤的原因。
OS 事件
錯誤數據也包含基礎 OS 和硬體事件，這些事件可能會導致應用程式失敗或重新啟動。 這類事件可以包含下列專案：
- 非計劃性裝置重新啟動所造成的核心錯誤
- 雲端 OS 更新
- 暫時性硬體問題
數據中包含 OS 事件，以協助您判斷應用程式錯誤是 OS 或硬體問題的結果，還是反映應用程式本身的問題。 如果事件數據顯示裝置開機為安全模式，您的應用程式可能無法啟動。
探索錯誤數據
如果您打算開發文本或工具來分析錯誤數據，但您沒有大量的裝置可用來報告錯誤，您可以使用 Azure Sphere 範例應用程式來產生這類數據進行測試。 Azure Sphere 範例存放庫中的 Tutorials/ErrorReporting 範例說明如何分析應用程式當機時回報的錯誤。 請遵循自述檔中的指示，使用 Visual Studio、Visual Studio Code 或命令行來建 置範例 。
當您從命令行部署應用程式而不使用調試程式時，OS 會在每次失敗時重新啟動它。 類似的事件會匯總，讓一個經常失敗的裝置不會遮罩其他裝置的錯誤，而且每個時間範圍最多有 8 次。 您可以從命令列部署範例而不進行偵錯，如下所示：
azsphere device sideload deploy --image-package <path to image package for the app>
產生和下載錯誤報告
錯誤和事件數據會每天上傳至 Azure Sphere 安全性服務。 請確定 Azure Sphere 裝置已使用 Wi-Fi 或 乙太網路 連線到因特網，以便與 Azure Sphere 安全性服務通訊。
執行下列命令，將報表下載至 CSV 檔案：
azsphere tenant download-error-report --destination error.csv開啟下載的 CSV 檔案，並尋找您的 元件識別碼。 您應該看到類似下列的錯誤描述：
AppExit (exit_code=0; component_id=685f13af-25a5-40b2-8dd8-8cbc253ecbd8; image_id=6d2646aa-c0ce-4e55-b7d6-7c206a7a6363)
您也可以使用 Azure Sphere 公用 API 來報告錯誤。
注意
- 最近回報的事件最多可能需要 24 小時才能下載。
- 如果裝置與 NTP 伺服器連線之前發生事件或錯誤，上傳至 AS3 之遙測中包含的事件時間戳可能不正確。 這會反映在從 AS3 下載的後續報表中 StartTime 數據行中不正確的專案。 在此情況下， 請使用報表的 EndTime 欄位來協助估計事件發生的時間。 此欄位包含雲端服務收到上傳遙測的時間，且一律會有有效的日期。
格式化錯誤數據
錯誤報告檔案中的時間戳和數據行的格式與一般 CSV 檔案不同。 如果您想要在 Excel 中檢視結果，您可以藉由建立新的數據行並新增自定義公式來重新格式化數據。
若要格式化匯出 CSV 檔案中的時間戳以使用 Excel：
建立新的 Timestamp 資料行，並為其建立自訂格式：
yyyy/mm/dd hh:mm:ss將下列公式新增至新 Timestamp 資料行中的儲存格，變更 F2 儲存格值以符合您的資料行和資料列：
=(DATEVALUE(LEFT(RawErrorReport!F2,10))+TIMEVALUE(RIGHT(RawErrorReport!F2,8)))
若要將 [描述] 字段分割成不同的數據行，請遵循下列步驟，變更 F2 單元格值以符合您的數據行和數據列：
建立名為 Shortname 或類似專案的新數據行，並將下列公式新增至儲存格：
=TRIM(LEFT(F2,FIND("(",F2)-1))建立資料行，其中 row1 標頭的名稱與參數值相同，並將下列公式新增至每個數據行中的數據格：
=IF(ISERROR(FIND("; " & H$1 & "=", SUBSTITUTE($F2,"(","; "))), "", MID($F2, FIND("; " & H$1 & "=", SUBSTITUTE($F2,"(","; ")) + (LEN(H$1) + 2), FIND("; ", SUBSTITUTE($F2,")","; "), FIND("; " & H$1 & "=", SUBSTITUTE($F2,"(","; "))) - FIND("; " & H$1 & "=", SUBSTITUTE($F2,"(","; ")) - (LEN(H$1) + 2)))