Fuchsia.feedback

新增：7

协议

ComponentDataRegister

在 fuchsia.feedback/data_register.fidl 中定义

注册可在反馈报告（崩溃、用户反馈或 bug 报告）中附加的有用数据。

组件可以使用此功能来扩充附加到所有反馈报告的数据。默认情况下，反馈服务会附加向平台公开的数据。此协议适用于某些产品中的某些组件已知但未向平台公开的数据。

墓志铭 ZX_ERR_INVALID_ARGS 表示客户端正在发送无效请求。请参阅下文，了解每个请求可能无效的原因。

墓志铭 ZX_ERR_NO_RESOURCES 表示服务器无法再存储其他组件数据，并且不会为新连接提供服务。

Upsert

更新或插入要包含在反馈报告中的额外组件数据。

系统会根据命名空间和每个注释键来决定是更新还是插入注释。如果同一命名空间中已存在给定键的注释，则更新该值，否则在该命名空间下插入具有该键的注释。

例如，假设服务器已保存以下数据（来自之前对 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

针对给定组件网址，更新或插入崩溃报告产品。

后续对同一组件网址调用 Upsert() 会覆盖该组件的 CrashReportingProduct。

如果组件本身也会提交崩溃报告，请首选 UpsertWithAck()，以避免竞态条件和错误归因。

请求

名称类型
component_url string:2083
product CrashReportingProduct

UpsertWithAck

执行 upsert 操作（见上文），并在操作完成后通知客户端。

这样，客户端就可以防止在提交崩溃报告和调用 Upsert 之间发生竞态。 否则，如果在 upsert 完成之前提交了崩溃报告，该崩溃报告将被归因于错误的产品，从而可能导致崩溃数据不正确。

请求

名称类型
component_url string:2083
product CrashReportingProduct

响应

<EMPTY>

DataProvider

在 fuchsia.feedback/data_provider.fidl 中定义

提供可附加到反馈报告中的有用数据，例如系统提交的崩溃报告、用户提交的用户反馈报告或开发者提交的 bug 报告。

GetAnnotations

返回一组关于设备状态的注释。

如果收集 annotations 时出现问题，则该字段可能为空。

这些注释与通过 GetSnapshot() 提供的注释相同。有些客户端只需要注释，而有些客户端则需要注释和快照，并且生成快照可能比收集注释花费的时间要长得多，例如，日志只是快照的一部分，而不是注释的一部分，可能需要一些时间。

请求

名称类型
params GetAnnotationsParameters

响应

名称类型
annotations Annotations

GetSnapshot

返回设备状态的快照。

如果生成快照时出现问题，snapshot 可能为空。

请求

名称类型
params GetSnapshotParameters

响应

名称类型
snapshot Snapshot

DeviceIdProvider

在 fuchsia.feedback/device_id_provider.fidl 中定义

提供设备的反馈 ID。

反馈 ID 是一个持久性 UUID，用于对反馈报告进行分组。该 ID 不得用于反馈以外的任何报告用途，例如，不得用于遥测。

GetId

返回设备的反馈 ID。

此方法遵循 hanging-get 模式，在自上次调用以来的 ID 发生更改之前，不会返回值。

请求

<EMPTY>

响应

名称类型
feedback_id string:64

LastRebootInfoProvider

在 fuchsia.feedback/last_reboot_info.fidl 中定义

获取有关设备上次关机原因的信息。我们使用术语“重新启动”而不是“关机”，因为许多开发者会用“重新启动”来表达有关关机的问题，并且大多数组件都想知道系统为何刚刚重新启动。

获取

请求

<EMPTY>

响应

名称类型
last_reboot LastReboot

STRUCTS

注释

在 fuchsia.feedback/annotation.fidl 中定义

注释及其纯 ASCII 字符串键。 注释是简短的字符串，例如开发板名称或 build 版本。

添加：23

字段类型说明默认
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 无默认应用

枚举

FilingError 灵活

类型：uint32

在 fuchsia.feedback/crash_reporter.fidl 中定义

新增：11

名称值说明
0
1
2
3
4

FilingSuccess flexible

类型：uint32

在 fuchsia.feedback/crash_reporter.fidl 中定义

“内存”是指非永久性位置，例如内存支持的文件系统。

新增：11

名称值说明
0
1
2
3
4

RebootReason flexible

类型：uint16

在 fuchsia.feedback/last_reboot_info.fidl 中定义

设备上次重启的原因。

名称值说明
0

如果服务器发送的新枚举值未在客户端中编译，则客户端将获取此值。

新增：9
2

设备从冷状态启动。

这很可能是因为设备长时间断电，或者设备首次使用 Fuchsia 启动。
3

设备因短暂断电而重启。

在某些硬件上，这可能是用户快速连续断开并重新连接设备电源的结果。
4

设备已重启，因为其电压降至允许的水平以下，但未降至 0。
5
6
7
8
19

设备因用户空间根作业终止而重启，这很可能是因为其某个关键进程崩溃。
28

设备重启是因为用户故意按住电源按钮将其硬重置。

新增：31
9

设备已重启，因为设备的最终用户发起了重启。

请勿用于任何与最终用户明确重启操作不直接相关的代码路径。 请改用下方的 DEVELOPER_REQUEST。
26

设备因卡住而由最终用户发起重启。

新增：31
22

设备重启是因为开发者发起了重启，通常是通过 shell 命令或类似接口（包括在自动化测试中）发起的。

新增：28
17

由于应用 OTA 失败，设备已重新启动，我们希望重试。
11

设备因过热而重启。
12

设备因会话问题或会话管理器无法从错误中恢复而重启。
15

设备已重启，因为系统管理器 (sysmgr) 无法从错误中恢复。
14

设备在恢复出厂默认设置后重新启动。 请参阅 fuchsia.recovery.FactoryReset。
16

设备已重启，因为由 sysmgr 管理的关键组件发生故障。
18

设备已重启，以应用 Zircon 启动映像的交换。
21

Starnix 无法识别的 Android 发起的重启原因。

新增：28
25

由 Android 发起的关机，Starnix 不知道原因。

新增：30
23

设备因 Android 调用“RescueParty”而重启。

添加：29
24

设备已重启，因为其中一个 Android 关键进程失败。

添加：29
27

设备电池电量耗尽。

新增：31
29

系统未能在预期时间内暂停或恢复。

新增：32
30

设备已重启，因为某个关键驱动程序发生故障。

Added: HEAD
10

设备因 OTA 而重启。
20

Netstack 组件正在更改版本。

已移除：NEXT 已添加：26

ShutdownAction flexible

类型：uint32

在 fuchsia.feedback/last_reboot_info.fidl 中定义

设备上次关机的方式。

添加：29

名称值说明
1
2
3
4

TABLES

注释

在 fuchsia.feedback/data_provider.fidl 中定义

关于设备状态的注释。

客户通常会将数据直接上传到服务器。因此，数据以任意键值对的形式提供，客户端可以直接将其转发到服务器。

序数字段类型说明
annotations2 vector<Annotation>:512

键值对字符串的向量。键必须是唯一的。

新增：25

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”，以便在按字典顺序排序时将相关注解（此处与“build”相关）分组在一起。

CrashReport 资源

在 fuchsia.feedback/crash_reporter.fidl 中定义

表示崩溃报告。

序数字段类型说明
program_name string:1024

发生崩溃的程序的名称，例如进程或组件的名称。

在内部，程序名称用于在无法立即上传报告时保留报告。因此，当用作文件系统路径时，它会被清理，例如，剥离任何 fuchsia-pkg:// 前缀。如果经过清理的程序名称为以下任一名称，则会返回 ZX_ERR_INVALID_ARGS：

  • ""
  • “.”
  • ".."
specific_report SpecificCrashReport

具体报告取决于崩溃类型。

如果需要发送有关崩溃程序的其他信息（例如，minidump），则应设置此字段。
annotations vector<Annotation>:32

一个由键值对字符串组成的向量，表示应附加到崩溃报告的任意数据。

键应具有唯一性，因为系统只会考虑向量中给定键的最新值。
attachments vector<Attachment>:16

由键值对（字符串到 VMO）组成的向量，表示应附加到崩溃报告的任意数据。

键应具有唯一性，因为系统只会考虑向量中给定键的最新值。

如果满足以下任一条件，系统将返回 ZX_ERR_INVALID_ARGS：

  • 键为“"”
  • 键为“.”
  • 键为“..”
  • 键包含正斜杠“/”
  • 键包含空格“ ”
  • 密钥包含可打印 ASCII 以外的字符
  • 以下键已预留给“反馈”使用：
    • annotations.json
    • minidump.dmp
    • snapshot_uuid.txt
    • snapshot.zip
    • uploadFileMinidump
event_id string:128

崩溃服务器可用于对与同一事件相关的多个崩溃报告进行分组的文本 ID。

与崩溃签名不同，具有相同 ID 的崩溃报告对应于不同的崩溃，但可以被视为属于同一事件，例如，低级服务器中的崩溃导致高级界面 widget 发生崩溃。
program_uptime zx/Duration

程序在崩溃前运行了多长时间。
crash_signature string:128

崩溃服务器可用于跟踪同一崩溃随时间变化情况的文本签名，例如“内核崩溃”或“OOM”。此签名将优先于从其余数据派生的任何自动签名。

与事件 ID 不同，具有相同签名的崩溃报告对应于同一崩溃，但发生在多个事件中，例如，每当服务器收到相同请求时，就会发生 null 指针异常。

必须与 [a-z][a-z-]* 匹配，即只能包含小写字母和连字符，否则会导致 ZX_ERR_INVALID_ARGS 墓志铭。
is_fatal bool

指明崩溃报告是否针对运行中的进程、组件或系统本身的异常停止。

导致严重崩溃报告的事件示例如下：

  • ELF 进程崩溃
  • 系统因内存不足而重新启动。
  • 系统因关键组件崩溃而重启。
  • 设备因过热而导致系统重启。

以下是会导致非严重崩溃报告的事件示例：

  • 在具有多个执行上下文的 Dart 程序中，运行时可能会选择终止该特定执行上下文，并为其（而非整个程序）提交崩溃报告。
  • 组件检测到严重事件（例如 OOM）可能很快就会发生，但不一定会发生。

此字段主要用于按致命、非致命和未知对崩溃进行分组，分别对应于该字段设置为 true、设置为 false 或未设置。
weight uint32

可选。用于指明此报告不仅代表此次崩溃。例如，如果选择仅针对每 10 个此类崩溃实例中的 1 个提交 bug，则此字段应设置为 10。

如果未设置该字段，则使用权重 1。明确设置的值 0 无效，将被拒绝。

新增：28

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 版”“正式版”。

如果未指定渠道，则不会向崩溃服务器报告任何渠道。

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 演变为支持新的 RebootReason 值且客户端尚未更新时，此字段非常有用。

如果提供了 |reason|，则此字段始终有值。不过，即使提供了此字段，|reason| 也可能并不总是有值。
reason RebootReason

设备上次重启的原因。
uptime zx/Duration

设备重启前的正常运行时间。这是自启动以来经过的时间，包括在挂起到空闲状态下花费的所有时间。
planned bool

上次重启是否为计划重启，即设备是否按照系统应用的计划重启。

此字段可让客户端知道上次重启是否是有计划的，而无需解析 |reason| 字段。

计划内重启本质上是正常重启。

添加：26
runtime zx/Duration

设备在重启前的运行时长。这是自启动以来经过的时间，不包括在挂起到空闲状态下花费的时间。

新增：27
action ShutdownAction

设备上次关机的方式。

添加：29

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 归档文件包含多个文件，分别对应于从平台收集的各种数据。通常，所有注释（设备正常运行时间、build 版本等）对应一个文件，每个附件（日志、检查数据等）对应一个文件。

如果请求中设置了 |response_channel|，则不设置。
annotations2 vector<Annotation>:512

键值对字符串的向量。键必须是唯一的。

虽然 ZIP 归档文件本身包含注释，但有些客户也希望单独获取注释，以便对其进行索引或扩充，因此我们也单独提供注释。

新增：25

TextBacktraceCrashReport 资源

在 fuchsia.feedback/crash_reporter.fidl 中定义

表示包含文本堆栈轨迹的崩溃报告。

Added: HEAD

序数字段类型说明
fuchsia_backtrace fuchsia.mem/Buffer

回溯的文本表示形式，采用 Fuchsia 的符号化标记格式。
process_name string:64

崩溃进程的名称。
process_koid zx/Koid

发生崩溃的进程的内核对象 ID。
thread_name string:64

发生崩溃的线程的名称。
thread_koid zx/Koid

发生崩溃的线程的内核对象 ID。

UNIONS

CrashReporter_FileReport_Result strict

在 fuchsia.feedback/crash_reporter.fidl 中定义

序数变体类型说明
response CrashReporter_FileReport_Response
err FilingError

SpecificCrashReport 灵活 资源

在 fuchsia.feedback/crash_reporter.fidl 中定义

表示特定的崩溃报告。

当服务器需要针对特定类型的崩溃（例如 JavaScript 的 RuntimeCrashReport）特殊处理其注释和附件时，添加一个新成员。

序数变体类型说明
native NativeCrashReport

适用于原生异常。
dart RuntimeCrashReport

适用于 Dart 异常。
text_backtrace TextBacktraceCrashReport

适用于 Fuchsia 符号化标记格式的文本堆栈轨迹。

Added: HEAD

常量

名称值类型说明
MAX_ANNOTATION_KEY_LENGTH 128 uint64

注解键的长度上限。

添加：23
MAX_ANNOTATION_VALUE_LENGTH 1024 uint64

注释值的长度上限。

添加：23
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_ANNOTATIONS2_PROVIDED 512 uint32
新增：25
MAX_NUM_ANNOTATIONS_PER_CRASH_REPORT 32 uint32
MAX_NUM_ANNOTATIONS_PER_NAMESPACE 16 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