收集及解譯錯誤資料

發行項
08/09/2023

錯誤和事件資料會每天上傳到 Azure 球體安全性服務。凡是有權存取特定租使用者的人，都可以下載該租使用者的資料。報告涵蓋租使用者中的所有裝置。

每個報告最多包含 1，000 個事件或 14 天的資料，以先到達者為准。資料可以寫入檔案或管道處理至腳本或應用程式。 CLI 只能傳回 1，000 個事件。使用 Azure 球體公用 API 指定頁面上傳回的事件數目上限。

您可以透過下列方式下載影響您裝置的錯誤和其他事件的相關資料：

使用 azsphere 租使用者下載錯誤報表 命令。系統會下載一個 CSV 檔案，其中包含目前租使用者內裝置回報的錯誤和事件資訊。
將 Azure 球體公用 API 用於錯誤報表。 API 端點會傳回 JSON 物件，您可以根據需求進行剖析。

不會從 RTApps 收集任何錯誤報表資料。如果您想要從 RTApps 記錄錯誤，您必須實作核心間通訊，以便將來自 RTApps 的錯誤傳達至高階應用程式，以便將錯誤資料記錄到網路服務。如需詳細資料，請參閱與高階應用程式通訊和與支援即時功能的應用程式通訊。

可用的資料類型

每個錯誤或事件所傳回的資料包括下列專案：

資料	描述
裝置識別碼	發生事件的裝置識別碼。
事件種類	事件是否已規劃或未計畫。作業系統和應用程式更新會被視為計畫的事件，而錯誤則是未計畫的事件。
活動課程	發生此事件的軟體元件：作業系統或應用程式。
事件計數	事件在 StartTime 和 EndTime 分隔的期間內發生的次數。
描述	事件的相關資訊。此欄位是一般欄位，並視事件及其來源而有所不同。對於應用程式，它可能包含結束碼、訊號狀態和訊號代碼，但不會修正欄位的確切內容。這包含事件的相關資訊，且來自時間範圍中第一次發生的事件。
開始時間	在使用中視窗開始的 UTC) 中 (日期和時間。
結束時間	在使用中視窗結束的 UTC) 中 (日期和時間。

[開始時間] 和 [結束時間] 會定義匯總事件資料的時間範圍。任何匯總事件群組的視窗最多可為 24 小時，且每個時間範圍最多可有 8 次。

應用程式事件

應用程式事件包括雲端載入的應用程式更新，以及當機、結束及其他類型的應用程式失敗。

應用程式更新是規劃的活動。針對 AppUpdate 事件，[描述] 欄位包含 AppUpdate 。

應用程式當機、結束、啟動失敗和類似事件都是非計畫的事件。如果是計畫外事件，[描述] 欄位的內容取決於發生事件的應用程式。下表列出可能出現在非計畫事件 [描述] 欄位中的欄位。

資料	描述
exit_status或exit_code	結束應用程式回報的狀態或程式碼。
signal_status	說明作業系統傳回當機之高階原因的整數。您可以在 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. 表示錯誤。
代碼	表示父訊號狀態內的詳細當機狀態。
component_id	當機之軟體元件的 GUID。
pc_modulename+offset	模組名稱，並位移到包含發生當機之程式碼的模組中。
lr_modulename+offset	模組名稱，並在模組中移至可能是通話函數的位移。

解讀 AppCrashes

您可以在signal_status和signal_code中找到關於 AppCrash 的大部分資訊。請依照下列步驟執行：

使用適用于signal_status的 Man 7 檔，首先查看標示為「標準訊號的訊號編號」的表格。在 x86/ARM 欄中，搜尋錯誤報表中 csv 指派給signal_status的值。找到之後，請記下最左邊欄中對應的訊號名稱。
向上捲動到標示為「標準訊號」的表格。符合先前判定的訊號名稱，並使用資料表來收集有關訊號所代表之訊號的詳細資訊。
在 signal_code 的 Man 7 檔和您先前找到的訊號名稱中，找到對應的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 的其他資訊：

訊號會在訊號人頁面描述的第 10 個區段中描述。值 11 的signal_status對應至 SIGSEGV 訊號。
SIGSEGV 表示發生不正確記憶體參照 (這通常是 Null 指標) 。
SI_Codes會在每個signal_status 的 SigAction 男士頁面描述的第三節中說明。雖然頁面不會列出每個si_code的索引編號，但您可以從索引 1 開始計算每個signal_status類別。透過查看從索引 1) 開始 (SIGSEGV si_codes清單，您可以看到第三個清單與SEGV_BNDERR相符。
SEGV_BNDERR表示已進行位址系結檢查失敗。

注意

常見的 AppCrash 包含 signal_status 值 9，也就是 SIG}訊號以及 SEND_SIG_PRIV si_code 。此狀態表示 OS 因超出記憶體使用量限制而使應用程式失去作用。若要深入瞭解應用程式記憶體限制，請參閱高層級應用程式中的記憶體使用。

解讀 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值來判斷錯誤發生的位置或時間。使用此值，在應用程式代碼內搜尋，以查看哪些結束程式碼訊息對應到錯誤報表中提供的值。然後，尋找應用程式中傳回結束碼訊息的函數及其原因。您可以檢視退貨聲明及其內容，找出錯誤的原因。

作業系統事件

錯誤資料也包括可能導致應用程式失敗或重新開機之可能影響應用程式的基礎作業系統和硬體事件。這類事件可能包含下列專案：

因核心錯誤所造成的非計畫裝置重新開機
雲端作業系統更新
暫時硬體問題

系統事件會包含在資料中，以協助您判斷應用程式錯誤是否為作業系統或硬體問題的結果，或是反映應用程式本身的問題。如果事件資料顯示裝置已開機至安全模式，您的應用程式可能無法啟動。

探索錯誤資料

如果您計畫開發用於分析錯誤資料的腳本或工具，但您沒有大量裝置可用來報告錯誤，您可以使用 Azure 球體範例應用程式來產生這類資料進行測試。 Azure 球體範例中的教學課程/錯誤報表範例會說明如何分析應用程式當機時回報的錯誤。依照已讀取檔中的指示，使用 Visual Studio、Visual Studio Code 或命令列建立範例。

當您從命令列部署應用程式時，若沒有偵錯程式，作業系統會在每次失敗時重新開機。類似的事件會匯總，讓一個經常失敗的裝置不會遮罩來自其他裝置的錯誤，而且每個時間範圍最多會出現八次。您可以從命令列部署樣本而不進行偵錯，如下所示：

Azure 球體 CLI
Azure 球體傳統 CLI

azsphere device sideload deploy --image-package <path to image package for the app>

azsphere device sideload deploy --imagepackage <path to image package for the app>

注意：Azure 球體傳統 CLI 即將淘汰。建議您使用新的 Azure 球體 CLI。

產生及下載錯誤報表

錯誤和事件資料會每天上傳到 Azure 球體安全性服務。確認 Azure 球體裝置已使用 Wi-Fi 或乙太網路連線到網際網路，以便與 Azure 球體安全性服務通訊。

執行下列命令以將報告下載至 CSV 檔案：
- Azure 球體 CLI
- Azure 球體傳統 CLI
```
azsphere tenant download-error-report --destination error.csv
```
```
azsphere tenant download-error-report --output error.csv
```
注意：Azure 球體傳統 CLI 即將淘汰。建議您使用新的 Azure 球體 CLI。
開啟下載的 CSV 檔案並尋找元件識別碼。您應該會看到類似下列的錯誤描述：

AppExit (exit_code=0; component_id=685f13af-25a5-40b2-8dd8-8cbc253ecbd8; image_id=6d2646aa-c0ce-4e55-b7d6-7c206a7a6363)

您也可以使用 Azure 球體公用 API 進行錯誤報表。

注意

最近報告的事件可能需要 24 小時才能下載。
如果在裝置與 NTP 伺服器連線之前發生事件或錯誤，上傳到 AS3 之遙測中所包含事件的時間戳記可能不正確。這會反映在從 AS3 下載的後續報告中 ，StartTime 欄中的不正確專案。在這種情況下，請使用報表的 EndTime 欄位來協助評估事件發生的時間。此欄位包含雲端服務收到上傳遙測的時間，且一律會有有效的日期。

格式錯誤資料

錯誤報表檔案中的時間戳記和資料行的格式與一般的 CSV 檔案不同。如果您想要在 Excel 中檢視結果，您可以建立新的欄並新增自訂公式，藉此重新格式化資料。

若要設定匯出 CSV 檔案中的時間戳記格式，以搭配 Excel 使用：

建立新的 [時間戳記] 欄並建立自訂格式：

yyyy/mm/dd hh:mm:ss
將下列公式新增至新 [時間戳記] 欄中的儲存格，將 F2 儲存格值變更為符合您的欄和列：

=(DATEVALUE(LEFT(RawErrorReport!F2,10))+TIMEVALUE(RIGHT(RawErrorReport!F2,8)))

若要將 [描述] 欄位分割成個別的欄，請依照下列步驟，變更 F2 儲存格值以符合您的欄和列：

建立名為 Shortname 或類似專案的新欄，並將下列公式新增至儲存格：

=TRIM(LEFT(F2,FIND("(",F2)-1))
建立列 1 標題與參數值名稱相同的欄，並將下列公式新增至每一欄的儲存格：

=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)))

共用方式為