Skip to main content

Reference: memfaultctl CLI

Useful links:

Basic Usage

Running memfaultctl --help prints the following:

# memfaultctl --help
Usage: memfaultctl [-c <config-file>] [-v] [-V] <command> [<args>]


A command line utility to adjust memfaultd configuration and trigger specific events for testing purposes.

Options:
-c, --config-file use configuration file
-v, --version show version information
-V, --verbose verbose output
--help display usage information

Commands:
enable-data-collection
enable data collection and restart memfaultd
disable-data-collection
disable data collection and restart memfaultd
enable-dev-mode enable developer mode and restart memfaultd
disable-dev-mode disable developer mode and restart memfaultd
export export (and delete) memfault data
reboot register reboot reason and call 'reboot'
request-metrics flush collectd metrics to Memfault now
show-settings show memfaultd settings
sync Upload all pending data to Memfault now
trigger-coredump trigger a coredump and immediately reports it to Memfault
(defaults to segfault)
write-attributes write device attribute(s) to memfaultd
add-battery-reading
add a reading to memfaultd's battery metrics in format
"[status string]:[0.0-100.0]".
report-sync-success
Report a successful sync for connectivity metrics
report-sync-failure
Report a failed sync for connectivity metrics
start-session Begin a session and start capturing metrics for it
end-session End a session and dump its metrics to MAR staging directory

The --config-file path defaults to /etc/memfaultd.conf. The settings you add in /etc/memfaultd.conf extend the built-in configuration file.

Developer mode

Enabling developer mode will change some settings of memfaultd to make development and testing easier:

  • Coredumps will not be rate-limited on device.
  • Fleet sampling will be disabled (all data collected will be uploaded).

To enable developer mode, use memfaultctl enable-dev-mode. This setting will be persisted across reboots. To disable developer mode, use memfaultctl disable-dev-mode.

Server-side rate limiting will apply to the device you're using to work on the integration process. Once you can see the device on the Memfault Web App, consider enabling Server-Side Developer Mode for it on the Memfault Web App to temporarily bypass these limits.

memfaultctl commands

add-battery-reading

Record the current state of the battery.

Battery readings are in the format CHARGE STATE:STATE OF CHARGE.

CHARGE STATE can be one of Unknown, Charging, Discharging, Not charging or Full.

This matches the values in /sys/class/power_supply/<supply_name>/status in the Kernel documentation.

<STATE OF CHARGE> is a number between 0 and 100 (decimals are accepted).

Example:

# memfaultctl add-battery-reading Charging:42

For more information, refer to our Core Metrics Battery documentation.

enable-data-collection

Call this command when your user has given consent to the collection of usage and performance information.

This setting is persisted across reboots and updates. To turn of collection, use memfaultctl disable-data-collection.

enable-dev-mode

Call this command to enable developer mode (see above) on this system.

This setting is persisted across reboots and updates. To disable developer mode, use memfaultctl disable-dev-mode.

export

# memfaultctl export --help
Usage: memfaultctl export [-n] -o <output> [-f <format>]

export (and delete) memfault data

Options:
-n, --do-not-delete
do not delete the data from memfault mar_staging
-o, --output where to write the MAR data (or '-' for standard output)
-f, --format output format (mar, chunk or chunk-wrapped)
--help display usage information

Call this command to export data collected by memfaultd to an output file. This is typically used on devices that do not have a direct connection to the Internet and where data will be uploaded via a proxy (a mobile application for example).

The output file size will be limited to approximately 10MB, you may need to call the command multiple times to export all the data. A success return code and an output file of 0 bytes is a sign that there is no data to export.

The output file is specified with the -o option. If you use -o -, the data will be streamed to the standard output. Success or error messages are always logged to the standard error (stderr) so they don't interfere with exported data.

Once the data has been exported and completely written to the output, memfaultd will delete it from the MAR staging area. You can use the -n option to download without deleting the data (in that case you will only have access to the first file if there is more than 10MB of data to export).

Memfault SDK for Linux currently support three export formats:

  • -f zip (default): the data will be exported as a zip file containing a folder for each MAR event.
  • -f chunk the data is exported as one Memfault chunk (same format is used by the Memfault MCU SDK).
  • -f chunk-wrapped the data is exported as one Memfault chunk and a 8 bytes header is added with the four bytes CHNK and the size of the data as one big-endian uint32.

Example:

$ memfaultctl export -o export1.zip
Export saved and data cleared from memfaultd.

$ memfaultctl export -o export2.zip
Nothing to export right now. You may want to try `memfaultctl sync`.

reboot

This command will write the provided reboot reason to the last_reboot_reason_file and restart the machine with the reboot command.

Example:

# memfaultctl reboot --reason 4

Refer to our list of reboot reasons.

report-sync-failure

Report a successful synchronization of the device. This is used to calculate the periodic connectivity metric.

report-sync-success

Report a successful synchronization of the device. This is used to calculate the periodic connectivity metric.

request-metrics

This command will restart collectd (to trigger a data collection event) and then send a SIGUSR1 to flush the metrics to Memfault.

show-settings

Prints the current configuration of memfaultd.

Example:

# memfaultctl show-settings
Base configuration (/etc/memfaultd.conf):
{ ... }

Runtime configuration:
{ }

Device configuration from memfault-device-info:
MEMFAULT_DEVICE_ID=qemu-tester
MEMFAULT_HARDWARE_VERSION=qemuarm64

VERSION=dev
GIT COMMIT=unknown

Features enabled:
attributes
reboot
swupdate
collectd
coredump

sync

Immediately process memfaultd queue.

memfaultd stores events in a queue and only processes it at a fixed interval (by default 1 hour - see upload_interval_seconds). Use memfaultctl sync to force memfaultd to immediately send all events to Memfault.

trigger-coredump

This command will force an immediate coredump which will be captured by memfaultd and immediately uploaded to Memfault. Use this command to verify that the Memfault SDK is configured properly and that your symbols have been uploaded.

Example:

$ memfaultctl trigger-coredump

write-attributes

Use this command to create or update device attributes. You can provide multiple attributes in one call.

# memfaultctl write-attributes APP_VERSION=1.4.2 ACTIVATED=true

Attributes uploaded with this command can only be used as device attributes and not as time series metrics in Memfault. Refer to our metrics guide to upload application-specific

The Memfault SDK does not attempt to avoid unnecessary calls. Every call to this command will eventually trigger a network request. You should avoid setting the same value repeatedly as this would increase network usage.

Attribute types

memfaultctl will try to guess the type of the attributes:

  • true/false are converted to boolean values;
  • Numbers are converted to float values;
  • Anything else is uploaded as a string.

To force memfaultctl to treat the value as a string, you can enclose the value with double-quote. You will typically need to escape the double quotes so they are not removed by the shell:

# memfaultctl write-attributes APP_VERSION=\\"1.4\\"

Queueing

In developer mode, attributes are flushed immediately to Memfault. Otherwise, they are stored in the queue and processed with other events.

Use memfaultctl sync to force an immediate synchronization of the attributes.

start-session

Use this command to start a session.

Optionally, gauge readings to be included in the subsequent metric report can be provided in the format <KEY>=<VALUE>.

This command will error if there is a not a session type with the provided name defined in /etc/memfaultd.conf. Starting a session type for which there is already a session ongoing is a no-op.

# memfaultctl start-session my-example-session my_gauge=4.2

end-session

Use this command to end a session.

Optionally, gauge readings to be included in the subsequent metric report can be provided in the format <KEY>=<VALUE>.

This command will error if there is a not a session of the provided type ongoing.

# memfaultctl end-session my-example-session my_gauge=4.2