Skip to main content

Custom Traces

Introduction

The Memfault SDK has the ability to capture Custom Traces, which are user-defined events recorded for critical errors that do not dump a core file to the Linux core handler.

Custom traces can be generated in several ways when working with the local memfaultd daemon:

Using memfaultctl CLI

The memfaultctl command-line tool provides a convenient way to save custom traces:

memfaultctl save-trace --program <program> --reason <reason> [--crash <crash>] [--source <source>] [--signature <signature>]

Options:

  • --program: name of program reporting the Trace (Required)
  • --reason: reason for Trace collection (Required)
  • --crash: whether or not the Trace represents a crash (Optional, default value: True)
  • --source: the source of the Trace (largely used for internal reporting) (Optional, default value: Unknown)
  • --signature: input for Memfault signature algorithm that determines which Traces are grouped together (Optional, default value: None)

Using HTTP API

You can also generate custom traces by making HTTP requests directly to the memfaultd daemon:

curl --header "Content-Type: application/json" \
--request POST \
--data '{
"signature": "SIGNATURE",
"crash": true,
"reason": "UpdateError",
"program": "ota.py"
}' \
http://127.0.0.1:8787/v1/trace/save -v

Both methods allow you to capture relevant events and provide the necessary context for effective debugging and monitoring.

Using pyfault

Python stacktraces can be captured using the pyfault python library. This library embeds into your python program installing a custom handler in the sys.excepthook. This converts the typical python stacktrace into the custom trace format expected by memfaultd and sends it to memfaultd over http. It is also published to pypi for convenience. See the readme for more in depth information on installation and usage.