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

NameType

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.

Request

NameType
component_url fuchsia.sys/component_url
product CrashReportingProduct

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.

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.

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

Request

NameType
params GetSnapshotParameters

Response

NameType
snapshot Snapshot

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.

Request

NameType

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

NameType

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.

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

Attachment

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.

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

CrashReporter_File_Response

Defined in fuchsia.feedback/crash_reporter.fidl

NameTypeDescriptionDefault

Screenshot

Defined in fuchsia.feedback/data_provider.fidl

An encoded image of the screen.

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

ENUMS

ImageEncoding

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

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
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.

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.

SYSTEM_FAILURE 13

The device rebooted because a core component was unable to recover from an error, e.g., the system manager crashed.

FACTORY_DATA_RESET 14

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

TABLES

ComponentData

Defined in fuchsia.feedback/data_register.fidl

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

OrdinalNameTypeDescription
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

Defined in fuchsia.feedback/crash_reporter.fidl

Represents a crash report.

OrdinalNameTypeDescription
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.

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.

CrashReportingProduct

Defined in fuchsia.feedback/crash_register.fidl

Product release information to report to the crash server.

OrdinalNameTypeDescription
1 name string

The product name on the crash server.

  • Missing this required field will result in a ZX_ERR_INVALID_ARGS epitaph.
2 version string

Optional product version of the component.

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.

GenericCrashReport

Defined in fuchsia.feedback/crash_reporter.fidl

Represents a generic crash report.

OrdinalNameTypeDescription
1 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".

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.

GetSnapshotParameters

Defined in fuchsia.feedback/data_provider.fidl

Parameters for the DataProvider::GetSnapshot() method.

OrdinalNameTypeDescription
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.

LastReboot

Defined in fuchsia.feedback/last_reboot_info.fidl

Information about why a device last rebooted.

OrdinalNameTypeDescription
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

Defined in fuchsia.feedback/crash_reporter.fidl

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

OrdinalNameTypeDescription
1 minidump fuchsia.mem/Buffer

The core dump in the Minidump format.

RuntimeCrashReport

Defined in fuchsia.feedback/crash_reporter.fidl

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

OrdinalNameTypeDescription
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

Defined in fuchsia.feedback/data_provider.fidl

Represents a snapshot.

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.

OrdinalNameTypeDescription
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.).

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

Defined in fuchsia.feedback/crash_reporter.fidl

NameTypeDescription
response CrashReporter_File_Response
err zx/status

SpecificCrashReport

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.

NameTypeDescription
generic GenericCrashReport

Intended for arbitrary crashes, e.g., OOM, out-of-disk.

native NativeCrashReport

Intended for a native exception.

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_PROGRAM_NAME_LENGTH 1024 uint32