blob: 4d19db6d9a90f2ccdc897e2bffe32a5d91cdb9a9 [file] [log] [blame]
// Copyright 2019 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
using fuchsia.mem;
using zx;
/// Provides the ability to file crash reports.
protocol CrashReporter {
/// 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.
File(resource struct {
report CrashReport;
}) -> (struct {}) error zx.status;
const MAX_PROGRAM_NAME_LENGTH uint32 = 1024;
const MAX_EVENT_ID_LENGTH uint32 = 128;
const MAX_CRASH_SIGNATURE_LENGTH uint32 = 128;
/// Represents a crash report.
type CrashReport = resource table {
/// The name of the program that crashed, e.g., the process or component's name.
1: program_name string:MAX_PROGRAM_NAME_LENGTH;
/// How long the program was running before it crashed.
6: program_uptime zx.duration;
/// 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.
2: specific_report SpecificCrashReport;
/// 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.
3: annotations vector<Annotation>:MAX_NUM_ANNOTATIONS_PER_CRASH_REPORT;
/// 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.
4: attachments vector<Attachment>:MAX_NUM_ATTACHMENTS_PER_CRASH_REPORT;
/// 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.
5: event_id string:MAX_EVENT_ID_LENGTH;
/// 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.
7: crash_signature string:MAX_CRASH_SIGNATURE_LENGTH;
/// 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.
8: is_fatal bool;
/// 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.
type SpecificCrashReport = flexible resource union {
1: reserved;
/// Intended for a native exception.
2: native NativeCrashReport;
/// Intended for a Dart exception.
3: dart RuntimeCrashReport;
const MAX_PROCESS_NAME_LENGTH uint32 = 64;
const MAX_THREAD_NAME_LENGTH uint32 = 64;
/// Represents a crash report for a native exception out of which the client has built a minidump.
type NativeCrashReport = resource table {
/// The core dump in the Minidump format.
1: minidump fuchsia.mem.Buffer;
/// The name of the crashed process.
2: process_name string:MAX_PROCESS_NAME_LENGTH;
/// The kernel object id of the crashed process.
3: process_koid zx.koid;
/// The name of the crashed thread.
4: thread_name string:MAX_THREAD_NAME_LENGTH;
/// The kernel object id of the crashed thread.
5: thread_koid zx.koid;
const MAX_EXCEPTION_TYPE_LENGTH uint32 = 128;
/// Represents a crash report for a runtime exception, applicable to most languages.
type RuntimeCrashReport = resource table {
/// The exception type, e.g., "FileSystemException".
1: exception_type string:MAX_EXCEPTION_TYPE_LENGTH;
/// The exception message, e.g., "cannot open file".
2: exception_message string:MAX_EXCEPTION_MESSAGE_LENGTH;
/// The text representation of the exception stack trace.
3: exception_stack_trace fuchsia.mem.Buffer;