Events

An Event is a message generated by a Device. The types include but are not limited to Heartbeats, Traces, and Installs.

Event Types

Event Type	Description
heartbeat	Contains useful hourly metrics and system vitals
trace	A Trace event, which adheres to the structure below

Request Schema

Event Type	Type	Description
type Required	String	What type of Event this is. One of the Event Types above Example: "heartbeat.hourly"
release_version Required	String	Version of the Release installed on the Device Example: "1.2.3"
device_serial Required	String	Device Unique Identifier (set by client) Example: ABCD1234 Example: "ABCD1234"
hardware_version Required	String	Hardware Version for the Device. Example: "hwrev1"
sdk_version Required	String	Memfault SDK Version on the Device Example: "0.1.0"
captured_date	DateTime	Date the device captured the event
event_info	JSON	Event data. Exact schema is determined by the Event Type
extra_info	JSON	Extra data. Memfault won't process this data, but will store it along with the Event

Event Info Payloads

The following structures are the only valid objects that are allowed in the event_info object of an Event.

Heartbeat Event

A heartbeat is like the "pulse" of a Device. It reports the vitals of the system, and gives Memfault an overview of what happened in the last hour.

The key-value pairs sent in the event_info.metrics field are required to be in string:number form. These metrics are parsed by Memfault and shown in dashboards. These metrics can be anything...be creative!

Some useful metrics to gather can include but are not limited to:

• Uptime
• Battery Percentage
• Bluetooth Bytes Sent/Received
• Wi-Fi Bytes Sent/Received
• Bluetooth Time Connected
• Heap Bytes Free/Allocated
• Time Asleep/Awake
• Flash Bytes Written/Read
• CPU/MCU Utilization

It's also useful to record usage metrics of your devices. For example, if we want to record metrics for a Parking Meter, we may also want to record the number of user interactions or number of coins inserted to measure usage.

Field	Type	Description
metrics	Object[string:number]	An object of a list of metrics as key:value pairs, where the key is a string and value is a number

{
  "type": "heartbeat",
  "release_version": "1.2.3",
  "device_serial": "ABCD1234",
  "hardware_version": "hwrev1",
  "sdk_version": "0.4.0",
  "event_info": {
    "metrics": {
      "battery_pct": 77,
      "uptime_s": 17663,
      "heap_free_b": 1227
    }
  },
  "extra_info": {
    "whatever": "you_want"
  }
}

Trace Event

An Event that is generally recorded and associated with a crash, reset, or assert. This event contains a micro-amount of data about the crash, usually on a few registers and a Trace Reason. With just this information, Memfault can group these events and surface Issues.

This is the smallest form of Traces. If you are looking for more detail about a particular type of crash, such as getting a full backtrace or a coredump of the system, Memfault can do that too. Please reach out!

Field	Type	Description
reason Required	Object[String:Number]	The Trace Reason given by the Device Example: See Table Below for all possible values
pc Required	Number	Register value of the PC (Program Counter) register at time of the Trace Example: 226689
lr	Number	Register value of the LR (Link Register) register at time of the Trace Example: 226574
sp	Number	Register value of the SP (Stack Pointer) register at time of the Trace Example: 6712

{
  "type": "trace",
  "release_version": "1.2.3",
  "device_serial": "ABCD1234",
  "hardware_version": "hwrev1",
  "sdk_version": "0.4.0",
  "event_info": {
    "reason": 32769,
    "pc": 226689,
    "lr": 226574,
    "sp": 6712
  },
  "extra_info": {
    "whatever": "you_want"
  }
}

Trace Reason

Reason Name	Value	Type	Notes
UNKNOWN	0x0000	Unknown
USER_SHUTDOWN	0x0001	Normal
USER_RESET	0x0002	Normal
FW_UPDATE	0x0003	Normal
LOW_POWER	0x0004	Normal
ERROR_MASK	0x8000	Error	Every error below is masked against this value
WDKWWDR	0x8000	Error	We Don't Know Why We Dangerously Rebooted wdkwwdr.com
ASSERT	0x8001	Error
WATCHDOG	0x8002	Error
BUS_FAULT	0x9100	ARM: Bus Fault
IBUSERR	0x9101	ARM: Bus Fault
PRECISERR	0x9102	ARM: Bus Fault
IMPRECISERR	0x9103	ARM: Bus Fault
UNSTKERR	0x9104	ARM: Bus Fault
STKERR	0x9105	ARM: Bus Fault
LSPERR	0x9106	ARM: Bus Fault
BFARVALID	0x9107	ARM: Bus Fault
MEM_FAULT	0x9200	ARM: Memory Faults
IACCVIOL	0x9201	ARM: Memory Faults
DACCVIOL	0x9202	ARM: Memory Faults
MUNSTKERR	0x9203	ARM: Memory Faults
MSTKERR	0x9204	ARM: Memory Faults
MLSPERR	0x9205	ARM: Memory Faults
MMARVALID	0x9206	ARM: Memory Faults
USAGE_FAULT	0x9300	ARM: Usage Faults
UNDEFINSTR	0x9301	ARM: Usage Faults
INVSTATE	0x9302	ARM: Usage Faults
INVPC	0x9303	ARM: Usage Faults
NOCP	0x9304	ARM: Usage Faults
UNALIGNED	0x9305	ARM: Usage Faults
DIVBYZERO	0x9306	ARM: Usage Faults
HARD_FAULT	0x9400	ARM: Hard Faults

Query Parameters

The following parameters can be used to filter Events.

Query Parameter	Type	Description
device	String[]	Device Unique Identifier (set by client) Example: ABCD1234
type	String[]	Type of Event Example: "heartbeat"
since	DateTime	Recorded after this date Example: "2019-01-19T05:01:13.000000+00:00"
until	DateTime	Recorded before this date Example: "2019-01-19T05:01:13.000000+00:00"
release	String[]	Versions of Releases Example: release=1.2.3&release=1.2.4
cohort	String[]	Events generated by Devices in these Cohorts Example: cohort=alpha&cohort=beta
sort	String	Sort key (listed below) Example: -created_date

Sort Parameters

Sort Parameter	Type	Description
received_date	DateTime	Date the Event was received by Memfault
captured_date	DateTime	Date the Event was recorded on the Device NOTE: will equal received_date if empty

Response Schema

{
  "data": {
    "type": "heartbeat",
    "device": {
      "id": 1,
      "device_serial": "ABCD1234",
      "hardware_version": "hwrev1"
    },
    "release": {
      "id": 1,
      "version": "1.2.3",
      "revision": "11d95ef20f7a048ce1da1a6891dd3e2f92c89d85"
    },
    "sdk_version": "0.4.0",
    "received_date": "2019-01-19T05:01:13.000000+00:00",
    "captured_date": "2019-01-19T05:01:13.000000+00:00",
    "event_info": {
      "metrics": {
        "heap_free": 43,
        "heap_blocks": 712,
        "anything_else": 0
      }
    },
    "user_info": {
      "anything": "you_want",
      "last_app_opened": "Timer"
    }
  }
}

📄️Upload Events

Upload many **Events** for a given **Project**

📄️List Events

List all **Events** for a given **Project**

📄️Retrieve an Event

Retrieve a single **Event**