fuchsia.feedback

Added: 7

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.

FileReport

Files a crash report and gives the final result of the operation.

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.

Warning: this could potentially take up to several minutes. Calling this function in a synchronous manner is not recommended.

Added: 11

Request

NameType
report CrashReport

Response

NameType
payload CrashReporter_FileReport_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.

A subsequent call to Upsert() for the same component URL overwrites the CrashReportingProduct for that component.

Prefer UpsertWithAck() if the component also files crash reports itself, to avoid race conditions and mis-attribution.

Request

NameType
component_url string[2083]
product CrashReportingProduct

UpsertWithAck

Upserts (see above) and notifies 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 attributed to the wrong product, leading to potentially incorrect crash data.

Request

NameType
component_url string[2083]
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.

Removed: 13

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_FileReport_Response

Defined in fuchsia.feedback/crash_reporter.fidl

FieldTypeDescriptionDefault
results FileReportResults No default

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

FilingError flexible

Type: uint32

Defined in fuchsia.feedback/crash_reporter.fidl

Added: 11

NameValueDescription
0
1
2
3
4

FilingSuccess flexible

Type: uint32

Defined in fuchsia.feedback/crash_reporter.fidl

"Memory" refers to a non-persistent location, e.g. a memory-backed filesystem.

Added: 11

NameValueDescription
0
1
2
3
4

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
0

RebootReason flexible

Type: uint16

Defined in fuchsia.feedback/last_reboot_info.fidl

Reasons why a device last rebooted.

Added: 9

NameValueDescription
0

The client will get this value if the server is sending a new enum value that the client was not compiled with.

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.

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.

4

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

5
6
7
8
19

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

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.

10

The device rebooted because of an OTA.

17

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

11

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

12

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

15

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

14

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

16

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

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
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
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.
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
program_name string[1024]

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

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.

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.

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.

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.

program_uptime zx/Duration

How long the program was running before it crashed.

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.

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 information to report to the crash server.

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

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.

FileReportResults

Defined in fuchsia.feedback/crash_reporter.fidl

Added: 11

OrdinalFieldTypeDescription
result FilingSuccess

The success type.

report_id string[64]

A non-empty value if |result| is FilingSuccess::REPORT_UPLOADED.

GetAnnotationsParameters

Defined in fuchsia.feedback/data_provider.fidl

Parameters for the DataProvider::GetAnnotations() method.

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

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

reason RebootReason

Why a device last rebooted.

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
minidump fuchsia.mem/Buffer

The core dump in the Minidump format.

process_name string[64]

The name of the crashed process.

process_koid zx/Koid

The kernel object id of the crashed process.

thread_name string[64]

The name of the crashed thread.

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
exception_type string[128]

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

exception_message string[4096]

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

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

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_FileReport_Result strict

Defined in fuchsia.feedback/crash_reporter.fidl

OrdinalVariantTypeDescription
response CrashReporter_FileReport_Response
err FilingError

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.

OrdinalVariantTypeDescription
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 4096 uint32
Added: 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
Added: 11
MAX_THREAD_NAME_LENGTH 64 uint32