fuchsia.feedback

新增日期：7

通訊協定

ComponentDataRegister

如 fuchsia.feedback/data_register.fidl

註冊可附加在意見報告中的資料 (當機、使用者意見或錯誤報告)。

元件可用來強化所有意見回饋報告附加的資料。根據預設，意見回饋服務會附加向平台公開的資料。這個通訊協定適用於在某些產品中由特定元件所識別，但該平台不會公開的資料。

epitaph ZX_ERR_INVALID_ARGS 表示用戶端傳送無效要求。如要瞭解各個要求無效的原因，請參閱下文。

epitaph ZX_ERR_NO_RESOURCES 表示伺服器無法再儲存其他元件資料，並且不會服務新連線。

新增或更新

更新/插入項目，也就是要納入意見回饋報告的額外元件資料，例如更新或插入內容。

命名空間和每個註解鍵都會用來決定是否要更新或插入註解。如果同一個命名空間中的特定鍵已含有註解，請更新該值，否則在該命名空間下方插入含有該鍵的註解。

舉例來說，假設這些是伺服器已保留的資料 (從先前對 Upsert() 的呼叫)：

{
  "bar": { # namespace
    "channel": "stable",
  },
  "foo": { # namespace
    "version": "0.2",
  }
}

然後：

Upsert({
  "namespace": "bar",
  "annotations": [
    "version": "1.2.3.45",
    "channel": "beta",
  ]
})

會導致伺服器目前保留：

{
  "bar": { # namespace
    "channel": "beta", # updated
    "version": "1.2.3.45" # inserted
  },
  "foo": { # namespace
    "version": "0.2", # untouched
  }
}

請注意，伺服器最多只會為每個命名空間保留 MAX_NUM_ANNOTATIONS_PER_NAMESPACE 不同的註解鍵，因此會取得最新的值。

要求

名稱類型
data ComponentData

回應

<EMPTY>

CrashReporter

定義於 fuchsia.feedback/crash_reporter.fidl

提供回報當機報告的功能。

FileReport

回報當機 report，並提供作業的最終結果。

這可能代表根據 FIDL 伺服器的設定，在本機當機報告資料庫中產生當機報告，或將當機報告上傳到遠端當機伺服器。

警告：這可能需要幾分鐘的時間。我們不建議以同步方式呼叫此函式。

新增時間：11 張

要求

名稱類型
report CrashReport

回應

名稱類型
payload CrashReporter_FileReport_Result

CrashReportingProductRegister

定義於 fuchsia.feedback/crash_register.fidl

允許元件選擇其他當機回報產品，針對該元件的檔案當機問題。

根據預設，系統會將平台偵測到的所有當機事件提報給當機伺服器上的單一產品。這個 API 可讓元件自行選擇產品，同時仍能享有平台的例外狀況處理和當機回報功能。

新增或更新

特定元件網址的更新/插入作業 (更新或插入) 當機回報產品。

對相同元件網址的後續呼叫 Upsert() 會覆寫該元件的 CrashReportingProduct。

如果元件也會檔案當機報告，請優先使用 UpsertWithAck()，以避免競爭狀況和歸因錯誤。

要求

名稱類型
component_url string[2083]
product CrashReportingProduct

UpsertWithAck

更新/插入 (如上所示) 並在作業完成後通知用戶端。

這可讓用戶端防止提交當機報告和呼叫 Upsert 之間的競爭。否則，如果在更新/插入完成前提交當機報告，當機報告將歸因至錯誤的產品，進而產生錯誤的當機資料。

要求

名稱類型
component_url string[2083]
product CrashReportingProduct

回應

<EMPTY>

DataProvider

定義於 fuchsia.feedback/data_provider.fidl

提供有助於附加至意見回饋報告的資料，例如系統提交的當機報告、使用者意見回饋報告，或開發人員提交的錯誤報告。

GetAnnotations

傳回一組關於裝置狀態的註解。

如果收集 annotations 時發生問題，系統可能就不會顯示任何內容。

這些註解與透過 GetSnapshot() 提供的註解相同 - 某些客戶只想註解和快照產生快照，但有些客戶希望同時取得註解和快照和產生快照，所需時間可能比收集註解還要長。例如，記錄只是快照的一部分，而非註解的一部分，且可能需要一些時間。

要求

名稱類型
params GetAnnotationsParameters

回應

名稱類型
annotations Annotations

GetScreenshot

傳回以提供的 encoding 編碼的目前檢視畫面圖片。

如果系統不支援編碼、裝置沒有螢幕，或記憶體不足，無法分配螢幕截圖圖片，screenshot 可以是空值。

螢幕截圖會與快照分開提供，因為呼叫端可能想在變更檢視畫面時，先在背景收集快照，然後再變更檢視畫面。同時有許多用戶端對這張螢幕截圖不感興趣。

要求

名稱類型
encoding ImageEncoding

回應

名稱類型
screenshot Screenshot?

GetSnapshot

傳回裝置狀態的快照。

如果產生快照時發生問題，snapshot 可能為空白。

要求

名稱類型
params GetSnapshotParameters

回應

名稱類型
snapshot Snapshot

DeviceIdProvider

定義於 fuchsia.feedback/device_id_provider.fidl

提供裝置的意見回饋 ID。

意見回饋 ID 是一組永久性的 UUID，可用於將意見回饋報告分組。請注意，ID 不應用於任何回報以外的用途 (例如不適合用於遙測資料)。

GetId

傳回裝置的意見回饋 ID。

這個方法會遵循掛斷模式，且在上次呼叫變更後 ID 才傳回值。

要求

<EMPTY>

回應

名稱類型
feedback_id string[64]

LastRebootInfoProvider

定義於 fuchsia.feedback/last_reboot_info.fidl

瞭解裝置上次關閉的原因。「重新啟動」一詞取代關機，因為許多開發人員在重新啟動時提出了有關關機的問題，且大多數元件都想瞭解系統重新啟動的原因。

取得

要求

<EMPTY>

回應

名稱類型
last_reboot LastReboot

結構化

註解

定義於 fuchsia.feedback/annotation.fidl

註解及其純 ASCII 字串鍵。註解是短字串，例如主面板名稱或版本。

廣闊類型說明預設
key string[128] 無預設
value string[1024] 無預設

附件 資源

定義於 fuchsia.feedback/attachment.fidl

附件及其純 ASCII 字串鍵。附件是較大的物件，例如記錄檔。可以是二進位或文字資料。

廣闊類型說明預設
key string[128] 無預設
value fuchsia.mem/Buffer 無預設

CrashReporter_FileReport_Response

定義於 fuchsia.feedback/crash_reporter.fidl

廣闊類型說明預設
results FileReportResults 無預設

螢幕截圖資源

定義於 fuchsia.feedback/data_provider.fidl

經過編碼的畫面圖片。

廣闊類型說明預設
image fuchsia.mem/Buffer 無預設
dimensions_in_px fuchsia.math/Size 無預設

ENUMS

FilingError 彈性

類型：uint32

定義於 fuchsia.feedback/crash_reporter.fidl

新增時間：11 張

名稱值說明
0
1
2
3
4

FilingSuccess 彈性

類型：uint32

定義於 fuchsia.feedback/crash_reporter.fidl

「記憶體」是指非永久位置，例如支援記憶體的檔案系統。

新增時間：11 張

名稱值說明
0
1
2
3
4

圖片編碼嚴格

類型：uint32

定義於 fuchsia.feedback/data_provider.fidl

圖片使用的編碼。

目前，系統僅支援 PNG，但日後需要時，可能會透過其他編碼傳回螢幕截圖。

名稱值說明
0

重新啟動原因 (彈性)

類型：uint16

定義於 fuchsia.feedback/last_reboot_info.fidl

裝置上次重新啟動的原因。

新增日期：9

名稱值說明
0

如果伺服器傳送未用於編譯的新列舉值，用戶端就會取得這個值。
2

裝置以冷狀態啟動。

這很可能是由於一段時間沒有電力，或是裝置首次使用 Fuchsia 啟動，
3

裝置因短暫斷電而重新啟動。

在某些硬體上，這可能是使用者中斷連線後，又重新連接裝置的電源供應器，導致快速連續播放。
4

由於裝置的電壓低於允許等級，而不低於 0，因此裝置已重新啟動。
5
6
7
8
19

使用者空間根工作已終止，很可能是因為其中一項重要程序當機，因此裝置已重新啟動。
9

裝置使用者啟動了重新啟動程序，因此裝置已重新啟動。使用者可以是代表真人或使用者與裝置互動的程式，例如 SL4F 或 RCS。
10

裝置因 OTA 而已重新啟動。
17

裝置因 OTA 套用失敗而想要重試，因此裝置已重新啟動。
11

系統判定裝置過熱，因此已重新啟動。
12

工作階段發生問題，或工作階段管理員無法從錯誤中復原，因此裝置已重新啟動。
15

由於系統管理員 (sysmgr) 無法從錯誤中復原，因此裝置已重新啟動。
14

恢復原廠設定後，裝置重新啟動。請參閱 fuchsia.recovery.FactoryReset。
16

由 sysmgr 管理的重要元件失敗，因此裝置已重新啟動。
18

裝置已重新啟動，以套用 Zircon 啟動映像檔的交換。

資料表

註解

定義於 fuchsia.feedback/data_provider.fidl

裝置狀態的註解。

用戶端通常會將資料直接上傳至伺服器。因此資料會採用任意鍵/值組合，用戶端可直接轉送至伺服器。

序數廣闊類型說明
annotations vector<Annotation>[64]

鍵/值組合的向量。金鑰保證不得重複。

ComponentData

如 fuchsia.feedback/data_register.fidl

已知元件 (但未向平台公開) 的資料，會顯示在意見回饋報告中。

序數廣闊類型說明
namespace string[32]

與資料相關聯的頂層命名空間：

  • 用於將相關資料分組，並減少命名空間間的資料鍵衝突。
  • 可能會由多個用戶端共用，例如，同一個元件中或不同元件可能會有多個用戶端共用相關資料，且這些用戶端都使用相同的命名空間。
  • 在所有意見回饋報表中，該命名空間內傳遞的每個資料鍵前面都會加上該註解。例如，如果命名空間是「foo」，則所有意見回饋報告都會將註解「version」顯示為「foo.version」。
  • 必須與 [a-z-]+ 相符，例如只能使用小寫字母和連字號，否則會產生 ZX_ERR_INVALID_ARGS 稱呼。
  • 不得與內部平台資料 (例如「build」，否則會產生 ZX_ERR_INVALID_ARGS 劇集。保留的命名空間清單屬於內部使用，目前可能會有變動。
annotations vector<Annotation>[16]

鍵/值組合的向量，例如<"version", "1.2.3.45">.

索引鍵：

  • 名稱不得重複，因為系統只會將其視為向量中特定鍵的最新值。
  • 必須符合 [a-z-.]+ 屬性，也就是只能使用小寫英文字母、連字號和半形句號。讓子名稱間距使用半形句號，例如「build.label」和「build.type」，讓系統在依字母順序排序時，將相關註解歸為同一組 (就此和「建構」相關)。

CrashReport 資源

定義於 fuchsia.feedback/crash_reporter.fidl

代表當機報告。

序數廣闊類型說明
program_name string[1024]

發生當機的程式名稱，例如程序或元件的名稱。
specific_report SpecificCrashReport

視當機類型而定的專屬報表。

如果需要傳送當機程式的其他資訊 (例如迷你傾印)，則應設定這個欄位。
annotations vector<Annotation>[32]

用於表示應附加至當機報表任意資料的鍵/值字串組合向量。

索引鍵不得重複，因為只會考慮向量中特定鍵的最新值。
attachments vector<Attachment>[16]

這個鍵/值字串對 VMO 組合的向量，代表應附加至當機報告的任意資料。

索引鍵不得重複，因為只會考慮向量中特定鍵的最新值。
event_id string[128]

當機伺服器可使用的文字 ID，將多個與相同事件相關的當機報告分組。

與當機簽章不同的是，當機報告具有相同的 ID 會對應至不同的當機事件，但可能會被視為同一個事件，例如低層級伺服器中的當機會導致高階 UI 小工具發生當機。
program_uptime zx/Duration

程式在停止運作前執行的時間長度。
crash_signature string[128]

當機伺服器可在一段時間內追蹤相同當機事件的文字簽名，例如：「kernel-panic」或「oom」此簽章的優先權高於其他資料所衍生的自動簽章。

與事件 ID 不同的是，共用相同簽章的當機報告會對應至相同的當機事件，但在多個事件中會發生，例如：每次要求相同要求時，伺服器中的空值指標例外狀況。

必須與 [a-z][a-z-]* 相符，例如只能使用小寫字母和連字號，否則會產生 ZX_ERR_INVALID_ARGS 稱呼。
is_fatal bool

指出當機報告是針對運作中程序、元件或系統本身的非典型停止程序。

導致嚴重當機報告的事件包括：

  • ELF 程序當機
  • 因記憶體不足而重新啟動
  • 因重大元件當機而重新啟動系統
  • 因裝置過熱而重新啟動

會導致不嚴重當機報告的事件包括：

  • 帶有許多執行情境的 Dart 程式中未偵測到的例外狀況。執行階段可以選擇終止特定執行情境，並提交當機報告，而非整個程式。
  • 偵測嚴重事件 (例如 OOM) 的元件可能很快就會發生，但不保證會發生。

這個欄位主要用於將當機事件依嚴重、非嚴重和不明類別分組，且每個都會對應設為 true、設為 false 或未設定的欄位。

CrashReportingProduct

定義於 fuchsia.feedback/crash_register.fidl

要向當機伺服器回報的產品資訊。

序數廣闊類型說明
name string

當機伺服器上的產品名稱。

  • 第一個字元必須是英數字元。其餘字元必須可列印，但不得為空格，且會在 ASCII 資料表中將值 33 到 127。其他字元都會產生 ZX_ERR_INVALID_ARGS 稱呼。
  • 缺少這個必填欄位會導致 ZX_ERR_INVALID_ARGS 稱呼。
version string

元件的選用產品版本。

  • 第一個字元必須是英數字元。其餘字元必須可列印，但不得為空格，且會在 ASCII 資料表中將值 33 到 127。其他字元都會產生 ZX_ERR_INVALID_ARGS 稱呼。

如未指定版本，系統就不會向當機伺服器回報任何版本。
channel string

元件的選用產品發布版本，例如「canary」、「beta」、「stable」。

如未指定管道，當機伺服器就不會回報任何版本。

FileReportResults

定義於 fuchsia.feedback/crash_reporter.fidl

新增時間：11 張

序數廣闊類型說明
result FilingSuccess

成功類型。
report_id string[64]

如果 |result| 為 FilingSuccess::REPORT_UPLOADED，則非空白值。

GetAnnotationsParameters

定義於 fuchsia.feedback/data_provider.fidl

DataProvider::GetAnnotations() 方法的參數。

序數廣闊類型說明
collection_timeout_per_annotation zx/Duration

系統會從平台中的多個位置平行收集註解，每個位置都有逾時時間。

collection_timeout_per_annotation 可讓用戶端控制每個註解集合的分配時間。讓客戶能在特定時間取得一部分的註解。

GetSnapshotParameters 資源

定義於 fuchsia.feedback/data_provider.fidl

DataProvider::GetSnapshot() 方法的參數。

序數廣闊類型說明
collection_timeout_per_data zx/Duration

快照會匯總平台中平行收集的各種資料 (裝置運作時間、記錄、檢查資料等)。每次資料收集都會在逾時內完成。

collection_timeout_per_data 可讓用戶端控制每個資料收集的所需時間。透過這種方式，用戶端就能在特定時間取得部分有效的快照。

請注意，這無法控制快照產生所需的總時間，也就是建構時間高於 collection_timeout_per_data，因為用戶端可在呼叫 GetSnapshot() 端使用逾時以控制總時間。
response_channel handle<channel>

如果設定這個旗標，快照封存會以 |fuchsia.io.File| 的形式傳送給這個管道，而不是在 |Snapshot| 回應的 |Archive| 欄位中設定。當用戶端在主機上且不支援 VMO 時，這通常很有用。

LastReboot

定義於 fuchsia.feedback/last_reboot_info.fidl

裝置上次重新啟動原因的相關資訊。

序數廣闊類型說明
graceful bool

指出上次重新啟動是否方便，也就是裝置未因錯誤而重新啟動，並以受控制的方式重新啟動。

這個欄位可讓用戶端在不剖析選用的 |reason| 欄位的情況下，瞭解上次重新啟動是否安全。這在未設定 |reason| 的情況下很實用；舉例來說，因為系統不知道重新啟動的合理程度，或 API 如何演變可支援新的 RestartReason 值，而用戶端尚未更新。

如有提供 |reason|，這個欄位一律會有值。不過，|reason| 不一定會提供這個欄位的值。
reason RebootReason

裝置上次重新啟動的原因。
uptime zx/Duration

裝置重新啟動前的運作時間。

NativeCrashReport 資源

定義於 fuchsia.feedback/crash_reporter.fidl

代表原生例外狀況 (用戶端已建立迷你傾印) 的當機報告。

序數廣闊類型說明
minidump fuchsia.mem/Buffer

以 Minidump 格式表示的核心傾印。
process_name string[64]

當機程序的名稱。
process_koid zx/Koid

當機程序的核心物件 ID。
thread_name string[64]

當機執行緒的名稱。
thread_koid zx/Koid

當機執行緒的核心物件 ID。

RuntimeCrashReport 資源

定義於 fuchsia.feedback/crash_reporter.fidl

代表執行階段例外狀況的當機報告，適用於大多數語言。

序數廣闊類型說明
exception_type string[128]

例外狀況類型 (例如「FileSystemException」。
exception_message string[4096]

例外狀況訊息，例如「無法開啟檔案」。
exception_stack_trace fuchsia.mem/Buffer

例外狀況堆疊追蹤的文字表示法。

快照資源

定義於 fuchsia.feedback/data_provider.fidl

裝置狀態的快照。

用戶端通常會將資料直接上傳至伺服器。因此資料會採用任意鍵/值組合，用戶端可直接轉送至伺服器。

序數廣闊類型說明
archive Attachment

<檔案名稱, ZIP 封存> 組合。

ZIP 封存檔包含數個檔案，分別對應從平台收集的各種資料。所有註解 (裝置運作時間、建構版本等) 通常會有一個檔案，每個附件 (記錄、檢查資料等) 也有一個檔案。

如果在要求中設定了 |response_channel|，就不會設定。
annotations vector<Annotation>[64]

鍵/值組合的向量。金鑰保證不得重複。

雖然註解已包含在 ZIP 封存檔中，但部分用戶端也希望個別為註解建立索引或增強註解，因此我們也將註解分開提供。

聯合國

CrashReporter_FileReport_Result 嚴格

定義於 fuchsia.feedback/crash_reporter.fidl

序數Variant類型說明
response CrashReporter_FileReport_Response
err FilingError

特定 CrashReport 彈性 資源

定義於 fuchsia.feedback/crash_reporter.fidl

代表特定當機報告。

當伺服器需要以特殊方式處理特定當機類型的特定註解和附件時，新增成員，例如 JavaScript 的 RuntimeCrashReport。

序數Variant類型說明
native NativeCrashReport

適用於原生例外狀況。
dart RuntimeCrashReport

適用於 Dart 例外狀況。

業者

名稱值類型說明
MAX_CRASH_SIGNATURE_LENGTH 128 uint32
MAX_EVENT_ID_LENGTH 128 uint32
MAX_EXCEPTION_MESSAGE_LENGTH 4096 uint32
新增日期：10 位
MAX_EXCEPTION_TYPE_LENGTH 128 uint32
MAX_NAMESPACE_LENGTH 32 uint32
MAX_NUM_ANNOTATIONS_PER_CRASH_REPORT 32 uint32
MAX_NUM_ANNOTATIONS_PER_NAMESPACE 16 uint32
MAX_NUM_ANNOTATIONS_PROVIDED 64 uint32
MAX_NUM_ATTACHMENTS_PER_CRASH_REPORT 16 uint32
MAX_PROCESS_NAME_LENGTH 64 uint32
MAX_PROGRAM_NAME_LENGTH 1024 uint32
MAX_REPORT_ID_LENGTH 64 uint32
新增時間：11 張
MAX_THREAD_NAME_LENGTH 64 uint32