Google is committed to advancing racial equity for Black communities. See how.

fuchsia.feedback

PROTOCOLS

ComponentDataRegister

Defined in fuchsia.feedback/data_register.fidl

Registers data useful to attach in feedback reports (crash, user feedback or bug reports).

This can be used by components to augment the data attached to all feedback reports. By default the Feedback service attaches data exposed to the platform. This protocol is useful for data known by certain components in certain products, but that is not exposed to the platform.

The epitaph ZX_ERR_INVALID_ARGS indicates that the client is sending invalid requests. See below for each request why they might be invalid.

The epitaph ZX_ERR_NO_RESOURCES indicates that the server can no longer store additional component data and will not service new connections.

Upsert

Upserts, i.e. updates or inserts, extra component data to be included in feedback reports.

The namespace and each annotation key are used to decide whether to update or insert an annotation. If an annotation is already present for a given key within the same namespace, update the value, otherwise insert the annotation with that key under that namespace.

For instance, assuming these are the data already held by the server (from previous calls to Upsert()):

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

then:

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

would result in the server now holding:

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

Note that the server will only hold at most MAX_NUM_ANNOTATIONS_PER_NAMESPACE distinct annotation keys per namespace, picking up the latest values.

Request

NameType
data ComponentData

Response

<EMPTY>

CrashReporter

Defined in fuchsia.feedback/crash_reporter.fidl

Provides the ability to file crash reports.

File

Files a crash report.

This could mean generating a crash report in a local crash report database or uploading the crash report to a remote crash server depending on the FIDL server's configuration.

Request

NameType
report CrashReport

Response

NameType
result CrashReporter_File_Result

CrashReportingProductRegister

Defined in fuchsia.feedback/crash_register.fidl

Allows a component to choose a different crash reporting product to file crashes for that component under.

By default, all crashes detected by the platform are filed under a single product on the crash server. This API allows components to choose their own product while still benefiting from the platform's exception handling and crash reporting.

Upsert

Upserts, i.e. updates or inserts, a crash reporting product for a given component URL.

Upsert() may be called multiple times for the same component_url, e.g., once for each launch of the component, in which case only the most recent call's product information will be used in crash reports.

UpsertWithAck should be preferred if the client manually files crash reports because a fire-and-forget is racy and client cannot know if their crash reports will successfully be attributed to the product they specify.

Request

NameType
component_url fuchsia.sys/component_url
product CrashReportingProduct

UpsertWithAck

Upsert and notify the client when the operation is complete.

This allows clients to prevent races between filing crash reports and calls to Upsert. Otherwise if a crash report is filed before the upsert completes, the crash report will be attriburted to the wrong product, leading to potentially incorrect crash data.

Request

NameType
component_url fuchsia.sys/component_url
product CrashReportingProduct

Response

<EMPTY>

DataProvider

Defined in fuchsia.feedback/data_provider.fidl

Provides data useful to attach to feedback reports, e.g., a crash report filed by the system, a user feedback report filed by a user or a bug report filed by a developer.

GetAnnotations

Returns a set of annotations about the device's state.

annotations may be empty if there was an issue collecting them.

These are the same annotations as provided through GetSnapshot() - some clients only want the annotations while others want both the annotations and the snapshot and generating the snapshot can take significantly more time than collecting the annotations, e.g., logs are only part of the snapshot and not part of the annotations and can take some time.

Request

NameType
params GetAnnotationsParameters

Response

NameType
annotations Annotations

GetScreenshot

Returns an image of the current view encoded in the provided encoding.

screenshot may be null if the encoding is not supported, the device does not have a display, or there is not enough memory to allocate the screenshot image.

The screenshot is provided separately from the snapshot as callers might want to block on this call before changing the view while collecting a snapshot in the background is fine. There are also a lot of clients that are not interested in the screenshot.

Request

NameType
encoding ImageEncoding

Response

NameType
screenshot Screenshot?

GetSnapshot

Returns a snapshot of the device's state.

snapshot may be empty if there was an issue generating the snapshot.

Request

NameType
params GetSnapshotParameters

Response

NameType
snapshot Snapshot

DataProviderController

Defined in fuchsia.feedback/data_provider_controller.fidl

Used to externally control the data provider, say when disk space is becoming scarce or user privacy settings change.

DisableAndDropPersistentLogs

Disables persistent logging for the remainder of the boot and drops any logs that have been persisted. Returns when both have completed. Persistent logging cannot be re-enabled at the moment due to the fact that a device is expected to reboot soon after persistent logging has been disabled.

Be aware that any snapshots created during the next boot will not have logs from the current boot and can make debugging difficult.

Request

<EMPTY>

Response

<EMPTY>

DeviceIdProvider

Defined in fuchsia.feedback/device_id_provider.fidl

Provides the device's feedback ID.

The feedback ID is a persisted UUID used to group feedback reports. The ID is not intended to be used for any reporting purposes other than feedback, e.g., not intended to be used for telemetry.

GetId

Returns the device's feedback ID.

This method follows the hanging-get pattern and won't return a value until the ID since the last call has changed.

Request

<EMPTY>

Response

NameType
feedback_id string[64]

LastRebootInfoProvider

Defined in fuchsia.feedback/last_reboot_info.fidl

Get information about why a device last shutdown. The term reboot is used instead of shutdown since many developers phrase their questions about shutdowns in terms of reboots and most components are interested in knowing why the system just rebooted.

Get

Request

<EMPTY>

Response

NameType
last_reboot LastReboot

STRUCTS

Annotation

Defined in fuchsia.feedback/annotation.fidl

An annotation and its plain ASCII string key. Annotations are short strings, e.g., the board name or the build version.

FieldTypeDescriptionDefault
key string[128] No default
value string[1024] No default

Attachment resource

Defined in fuchsia.feedback/attachment.fidl

An attachment and its plain ASCII string key. Attachments are larger objects, e.g., log files. They may be binary or text data.

FieldTypeDescriptionDefault
key string[128] No default
value fuchsia.mem/Buffer No default

CrashReporter_File_Response

Defined in fuchsia.feedback/crash_reporter.fidl

<EMPTY>

Screenshot resource

Defined in fuchsia.feedback/data_provider.fidl

An encoded image of the screen.

FieldTypeDescriptionDefault
image fuchsia.mem/Buffer No default
dimensions_in_px fuchsia.math/Size No default

ENUMS

ImageEncoding strict

Type: uint32

Defined in fuchsia.feedback/data_provider.fidl

The encoding used for the image.

Today, only PNG is supported, but in the future the screenshot could be returned in other encodings if need arises.

NameValueDescription
PNG 0

RebootReason strict

Type: uint16

Defined in fuchsia.feedback/last_reboot_info.fidl

Reasons why a device last rebooted.

NameValueDescription
COLD 2

The device booted from a cold state.

This is most likely the result of an extended period of time without power or a device booting with Fuchsia for the first time.

BRIEF_POWER_LOSS 3

The device rebooted due to a brief loss of power.

On some hardware this could be the result of a user disconnecting, then reconnecting their device's power supply in rapid succession.

BROWNOUT 4

The device rebooted because its voltage dipped below an allowable level without going to 0.

KERNEL_PANIC 5
SYSTEM_OUT_OF_MEMORY 6
HARDWARE_WATCHDOG_TIMEOUT 7
SOFTWARE_WATCHDOG_TIMEOUT 8
ROOT_JOB_TERMINATION 19

The device rebooted because the userspace root job was terminated, most likely because one of its critical processes crashed.

USER_REQUEST 9

The device rebooted because a user of the device initiated the reboot. A user can be a human or a program that interacts with the device on behalf of a human, such as SL4F or RCS.

SYSTEM_UPDATE 10

The device rebooted because of an OTA.

RETRY_SYSTEM_UPDATE 17

The device rebooted because applying the OTA failed and we want to retry.

HIGH_TEMPERATURE 11

The device rebooted because it was determined to be too hot.

SESSION_FAILURE 12

The device rebooted because of an issue with a session or because the session manager was unable to recover from an error.

SYSMGR_FAILURE 15

The device rebooted because the system manager (sysmgr) was unable to recover from an error.

FACTORY_DATA_RESET 14

The device rebooted following a data reset to factory defaults. See fuchsia.recovery.FactoryReset.

CRITICAL_COMPONENT_FAILURE 16

The device rebooted because a critical component managed by sysmgr has failed.

ZBI_SWAP 18

The device rebooted to apply the swap of Zircon boot images.

TABLES

Annotations

Defined in fuchsia.feedback/data_provider.fidl

Annotations about the device's state.

Clients typically upload the data straight to servers. So the data comes in the form of arbitrary key-value pairs that clients can directly forward to the servers.

OrdinalFieldTypeDescription
1 annotations vector<Annotation>[64]

A vector of key-value string pairs. Keys are guaranteed to be unique.

ComponentData

Defined in fuchsia.feedback/data_register.fidl

Data known to a component, but not exposed to the platform, to attach to feedback reports.

OrdinalFieldTypeDescription
1 namespace string[32]

The top-level namespace associated with the data:

  • Is intended to group related data together and reduce data key collisions across namespaces.
  • May be shared by multiple clients, e.g., there could be multiple clients within the same component or across components that want to expose related data and they would all use the same namespace.
  • Will be prefixed to every data key passed within that namespace in all feedback reports, e.g., the annotation "version" would appear as "foo.version" in all feedback reports if the namespace is "foo".
  • Must match [a-z-]+, i.e. only lowercase letters and hyphens or this will result in a ZX_ERR_INVALID_ARGS epitaph.
  • Must not match a reserved namespace used internally for platform data, e.g., "build", or this will result in a ZX_ERR_INVALID_ARGS epitaph. The list of reserved namespaces is internal and subject to change for now.
2 annotations vector<Annotation>[16]

A vector of key-value string pairs, e.g., <"version", "1.2.3.45">.

Keys:

  • Should be unique as only the latest value for a given key in the vector will be considered.
  • Must match [a-z-.]+, i.e. only lowercase letters, hyphens and periods. Use periods for sub-namespacing, e.g., "build.label" and "build.type", so that related annotations are grouped together (here related to "build") when sorted lexicographically.

CrashReport resource

Defined in fuchsia.feedback/crash_reporter.fidl

Represents a crash report.

OrdinalFieldTypeDescription
1 program_name string[1024]

The name of the program that crashed, e.g., the process or component's name.

6 program_uptime zx/duration

How long the program was running before it crashed.

2 specific_report SpecificCrashReport

The specific report that depends on the type of crashes.

This field should be set if additional information about the crashing program needs to be sent, e.g., a minidump.

3 annotations vector<Annotation>[32]

A vector of key-value string pairs representing arbitrary data that should be attached to a crash report.

Keys should be unique as only the latest value for a given key in the vector will be considered.

4 attachments vector<Attachment>[16]

A vector of key-value string-to-VMO pairs representing arbitrary data that should be attached to a crash report.

Keys should be unique as only the latest value for a given key in the vector will be considered.

5 event_id string[128]

A text ID that the crash server can use to group multiple crash reports related to the same event.

Unlike the crash signature, crash reports sharing the same ID correspond to different crashes, but can be considered as belonging to the same event, e.g., a crash in a low-level server causing a crash in a high-level UI widget.

7 crash_signature string[128]

A text signature that the crash server can use to track the same crash over time, e.g., "kernel-panic" or "oom". This signature will take precedence over any automated signature derived from the rest of the data.

Unlike the event ID, crash reports sharing the same signature correspond to the same crash, but happening over multiple events, e.g., a null pointer exception in a server whenever asked the same request.

Must match [a-z][a-z-]* i.e. only lowercase letters and hyphens or this will result in a ZX_ERR_INVALID_ARGS epitaph.

8 is_fatal bool

Indicates whether the crash report is for the atypical stop of a running process, component, or the system itself.

Examples of events that result in fatal crash reports are:

  • an ELF process crashing
  • the system rebooting because it ran out of memory.
  • the system rebooting because a critical component crashed.
  • the system rebooting because the device was too hot.

Examples of events that result in non-fatal crash reports are:

  • an uncaught exception in a Dart program with many execution contexts. The runtime may chose to terminate that specific execution context and file a crash report for it instead of the whole program.
  • a component detecting a fatal event (like an OOM) may occur soon, but isn't guaranteed to occur.

This field is primarily used for grouping crashes by fatal, not fatal, and unknown, each corresponding to the field being set to true, set to false, or not set respectively.

CrashReportingProduct

Defined in fuchsia.feedback/crash_register.fidl

Product release information to report to the crash server.

OrdinalFieldTypeDescription
1 name string

The product name on the crash server.

  • The first character has to be alphanumeric. The remaining characters must be printable, but cannot be a space, which leaves values 33 to 127 in the ASCII table. Any other characters will result in a ZX_ERR_INVALID_ARGS epitaph.
  • Missing this required field will result in a ZX_ERR_INVALID_ARGS epitaph.
2 version string

Optional product version of the component.

  • The first character has to be alphanumeric. The remaining characters must be printable, but cannot be a space, which leaves values 33 to 127 in the ASCII table. Any other characters will result in a ZX_ERR_INVALID_ARGS epitaph.

If no version is specified then none is reported to the crash server.

3 channel string

Optional product release channel for the component, e.g., "canary", "beta", "stable".

If no channel is specified then none is reported to the crash server.

GetAnnotationsParameters

Defined in fuchsia.feedback/data_provider.fidl

Parameters for the DataProvider::GetAnnotations() method.

OrdinalFieldTypeDescription
1 collection_timeout_per_annotation zx/duration

Annotations are collected in parallel from various places in the platform, each with a timeout.

collection_timeout_per_annotation allows clients to control how much time is given to each annotation collection. It enables clients to get a partial set of annotations under a certain time.

GetSnapshotParameters resource

Defined in fuchsia.feedback/data_provider.fidl

Parameters for the DataProvider::GetSnapshot() method.

OrdinalFieldTypeDescription
1 collection_timeout_per_data zx/duration

A snapshot aggregates various data from the platform (device uptime, logs, Inspect data, etc.) that are collected in parallel. Internally, each data collection is done within a timeout.

collection_timeout_per_data allows clients to control how much time is given to each data collection. It enables clients to get a partial yet valid snapshot under a certain time.

Note that this does not control how much total time the snapshot generation may take, which is by construction higher than collection_timeout_per_data, as clients can control the total time by using a timeout on the call to GetSnapshot() on their side.

2 response_channel handle<channel>

If set, the snapshot archive will be sent as a |fuchsia.io.File| over this channel instead of being set in the |archive| field in the |Snapshot| response. This is typically useful if the client is on the host and does not support VMOs.

LastReboot

Defined in fuchsia.feedback/last_reboot_info.fidl

Information about why a device last rebooted.

OrdinalFieldTypeDescription
1 graceful bool

Whether the last reboot was graceful, i.e. the device didn't reboot in response to an error and rebooted in a controlled manner.

This field allows clients to know whether the last reboot was graceful without having to parse the optional |reason| field. This is useful when |reason| is not set, i.e. because the system doesn't know more than the fact that the reboot was graceful, or when the API evolves to support new RebootReason values and the clients hasn't been updated yet.

This field is always has a value if |reason| is provided. However, |reason| might not always have a value this field is provided.

2 reason RebootReason

Why a device last rebooted.

3 uptime zx/duration

The uptime of the device before it rebooted.

NativeCrashReport resource

Defined in fuchsia.feedback/crash_reporter.fidl

Represents a crash report for a native exception out of which the client has built a minidump.

OrdinalFieldTypeDescription
1 minidump fuchsia.mem/Buffer

The core dump in the Minidump format.

2 process_name string[64]

The name of the crashed process.

3 process_koid zx/koid

The kernel object id of the crashed process.

4 thread_name string[64]

The name of the crashed thread.

5 thread_koid zx/koid

The kernel object id of the crashed thread.

RuntimeCrashReport resource

Defined in fuchsia.feedback/crash_reporter.fidl

Represents a crash report for a runtime exception, applicable to most languages.

OrdinalFieldTypeDescription
1 exception_type string[128]

The exception type, e.g., "FileSystemException".

2 exception_message string[2048]

The exception message, e.g., "cannot open file".

3 exception_stack_trace fuchsia.mem/Buffer

The text representation of the exception stack trace.

Snapshot resource

Defined in fuchsia.feedback/data_provider.fidl

Snapshot about the device's state.

Clients typically upload the data straight to servers. So the data comes in the form of arbitrary key-value pairs that clients can directly forward to the servers.

OrdinalFieldTypeDescription
1 archive Attachment

A <filename, ZIP archive> pair.

The ZIP archive contains several files corresponding to the various data it collected from the platform. There is typically one file for all the annotations (device uptime, build version, etc.) and one file per attachment (logs, Inspect data, etc.).

Not set if |response_channel| was set in the request.

2 annotations vector<Annotation>[64]

A vector of key-value string pairs. Keys are guaranteed to be unique.

While the annotations are included in the ZIP archive itself, some clients also want them separately to index or augment them so we provide them separately as well.

UNIONS

CrashReporter_File_Result strict

Defined in fuchsia.feedback/crash_reporter.fidl

Ordinal
VariantTypeDescription
1 response CrashReporter_File_Response
2 err zx/status

SpecificCrashReport flexible resource

Defined in fuchsia.feedback/crash_reporter.fidl

Represents a specific crash report.

Add a new member when the server needs to special case how it handles certain annotations and attachments for a given type of crashes, e.g., a RuntimeCrashReport for Javascript.

Ordinal
VariantTypeDescription
1
2 native NativeCrashReport

Intended for a native exception.

3 dart RuntimeCrashReport

Intended for a Dart exception.

CONSTANTS

NameValueTypeDescription
MAX_CRASH_SIGNATURE_LENGTH 128 uint32
MAX_EVENT_ID_LENGTH 128 uint32
MAX_EXCEPTION_MESSAGE_LENGTH 2048 uint32
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_THREAD_NAME_LENGTH 64 uint32