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. For further reference, see: https://docs.memfault.com/docs/linux/reference-memfaultctl-cli

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
  add-custom-data-recording
                    Add custom data recording to memfaultd

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, metric readings to be included in the subsequent Metric Report can be provided in the format <KEY>=<VALUE>. The value can be a number or a string.

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, metric readings to be included in the subsequent Metric Report can be provided in the format <KEY>=<VALUE>. The value can be a number or a string.

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 my_string=example

add-custom-data-recording​

Use this command to add custom data recording. This can be useful for attaching project specific data to your device's timeline. For more information on custom data recording, refer to the documentation on custom data recordings.

The command takes a string indicating the type of data recording, an absolute file path, and a list of comma separated MIME types as arguments. Additionally an optional duration and start time can be provided.

$ memfaultctl add-custom-data-recording recording_reason /absolute/path/to/file text/plain,text/csv
Last updated on
This page is human-authored. If you see any errors, outdated information, or any other suggestions for improving the contents, please contact us!