Use Loggingctl to Manage System Logs

Logging Control CLI (LoggingCtl) is a command-line interface (CLI) tool for managing, viewing, and testing logging data on Vega devices. It also provides access to crash reports (ACR files) stored on the device. To access the loggingctl command, you must enter the Vega device shell using the vega exec vda shell command. This tool helps you:

Debug app issues through real-time log monitoring.
Configure logging levels and rates for different processes.
Access and analyze stored logs and crash reports.
Manage log storage and retention.
Investigate system issues through diagnostic data.

Start or restart LoggingCtl after installing new apps

LoggingCtl determines log permissions based on apps installed when the session starts. Apps installed after LoggingCtl begins won’t show logs until you restart the LoggingCtl session.

Basic usage

$ loggingctl
Logging CTL

Usage: loggingctl <COMMAND>

Commands:
  config  Config commands - edit logging system priority and rate limits
  log     Log viewing commands - query runtime logs generated on device
  vault   Vault commands - query logging and crash data archived on device
  test    Test commands - commands used for system testing. Internal use only
  help    Print this message or the help of the given subcommand(s)

Options:
  -h, --help     Print help
  -V, --version  Print version

Configuration commands

Use loggingctl config commands to control logging behavior for your apps.

$ loggingctl config [OPTIONS]

Options:
  --set-level <PROCESS> <LEVEL>    Set minimum priority level (e.g., "my-service info")
  --get-level <PROCESS>            Get minimum priority level
  --mute <PROCESS>                 Mute all logs
  --set-rate <PROCESS> <RATE>      Set max logging rate limit (e.g., "my-service 100")
  --get-rate <PROCESS>             Get max logging rate limit
  -h, --help                       Print help

Reset configuration

To reset logging configuration to defaults:

For rate limits: Restore the default rate with --reset. Use --reset rather than setting the value by hand, because an explicit value leaves an override in place while --reset clears it:
loggingctl config --reset <PROCESS>
The default rate is 300 lines per second, per process. Valid rates are 1 to 60000 inclusive. loggingctl rejects 0 and any value above 60000.

For log levels: Set the level back to the default (info on release builds, debug on debug builds):
loggingctl config --set-level <PROCESS> info

Log budget and suppression

Each process has a log budget. When your app emits log lines faster than the budget allows, the logging library suppresses the excess: those lines are discarded inside your process and never reach the log backend. Suppression is silent to your code. The logging call returns normally whether the line was recorded or dropped, so a log with a gap looks the same as a log where nothing happened. This behavior is most noticeable on debug builds, which log more and reach the budget sooner. The default budget is 300 lines per second, per process. The minimum level is info on release builds and debug on debug builds. Budgets are independent for each combination of log tag and severity level. A chatty debug logger does not consume the budget of an info logger, and the other way around. A clean error stream does not mean nothing was dropped at info. Repeated over-emission escalates the suppression window (for example, 1, 2, 4, 16, and up to 256 seconds), and the window relaxes back one step per quiet period. A 256-second window means that tag and level have been dark for more than four minutes, so reduce your log volume or raise your budget before you draw conclusions from that log.

Detect suppression

The logging library writes a warning-level message under your app’s own identity when it starts suppressing, and another when it stops. The message appears in two forms. Process-wide, reporting the level:

lc_ProcessConfigManager Process exceeds log limit of [300] lps, [info] logs will be temporarily suppressed for [1] sec
lc_ProcessConfigManager Log suppression ended at level [info]. [42] logs were suppressed at this level.

Per tag, not reporting the level:

apmf.core.logconfig.config_monitor: Process exceeds log limit of [300] lps for tag [com.mycompany.myapp], logs will be temporarily suppressed for [1] sec
apmf.core.logconfig.config_monitor: Last log suppression ended for tag [com.mycompany.myapp]. [51] logs suppressed

Search for both wordings, and match case-insensitively on suppress, because the exact casing can vary between releases. The counts differ by design: the first counts per level across the whole process, the second counts per tag across all levels. To find these messages, filter the warning stream for your app and scan for suppression:

loggingctl log -v <YOUR_PACKAGE_ID> -p warning -f          # live
loggingctl log -v <YOUR_PACKAGE_ID> -p warning -S today    # after the fact

When you read the counts:

The count appears only on the message that reports suppression ending. While suppression is active, no count is reported.
The counter resets after each episode. Three episodes of 40 lines report three separate [40]s, not [120].
If your process exits while suppression is active, the ending message never arrives and the count is lost.
These warnings are not themselves rate limited, so the budget cannot suppress them.

Reduce dropped lines

If you are being suppressed, reduce volume first: log one line per state change instead of per iteration, and aggregate counters into a periodic summary. If you still need more throughput, raise the rate for the process:

loggingctl config --set-rate <YOUR_PACKAGE_ID> 1000

Reset to the default when you are done:

loggingctl config --reset <YOUR_PACKAGE_ID>

Log commands

Use loggingctl log commands to view logs from systemd-journald memory in real-time or from stored data. loggingctl log commands only show logs from the current session by default. To see older logs, use the --boot option on Vega Virtual Device. For Fire TV Stick, view previous logs using loggingctl vault commands.

$ loggingctl log
Log viewing commands - query runtime logs generated on device

Usage: loggingctl log [OPTIONS]

Options:
-f, --follow                            Follow logs being recorded
-p, --priority <PRIORITY>               Filter by priority; filters only given priority. Can be defined more than once
-k, --kernel                            Filter only kernel logs (NOT IMPLEMENTED)
-t, --identity <IDENTITY>               Filter by SYSLOG_IDENTIFIER. Can be defined more than once
-a, --tag <TAG>                         Filter by log tag string. Can be defined more than once
-b, --boot <BOOT>                       Filter by boot ID. Can be defined more than once
-P, --pid <PID>                         Filter by PID. Can be defined more than once
-T, --tid <TID>                         Filter by TID. Can be defined more than once
-F, --facility <FACILITY>               Filter by SYSLOG_FACILITY. Can be defined more than once
-S, --since <SINCE>                     Filter since given time. Can only be defined once
-U, --until <UNTIL>                     Filter until given time. Can only be defined once
-o, --output-format <OUTPUT_FORMAT>     Specify output format, "short_precise" or "short_concise" (default). Invalid string will set output to default. Can only be defined once
-v, --vpkg <VPKG>                       Filter by package ID, can be defined more than once
-h, --help Print help

Recommended filtering to view logs

For React Native and JavaScript developers, use the package ID filter (-v) to view logs from your specific app:

# Filter logs by your app's package ID (recommended)
loggingctl log -v "com.amazondeveloper.yourapp" -f

# Filter by priority level (works with console.* methods)
loggingctl log -v "com.amazondeveloper.yourapp" -p err -f

To stop following logs, press Ctrl+C. If logs don’t appear for your app: LoggingCtl only detects apps installed before the session starts. If you installed your app after starting LoggingCtl, reinstall the app and restart the session:

Install the app manually:

vega exec vda shell vpm install <path_to_vpkg>

Start LoggingCtl:
vega exec vda shell loggingctl log -f

Start the app using vmsgr send:

vega exec vda shell vmsgr send pkg://com.amazondeveloper.yourapp.main

JavaScript logging considerations

When using JavaScript logging in your Vega apps: Recommended approach: Use console.* methods for proper log level filtering:

console.log("Info message");     // Maps to INFO level
console.warn("Warning message"); // Maps to WARNING level
console.error("Error message");  // Maps to ERROR level

Supported argument keywords

The --priority, --facility, --since, --until, and --output-format commands accept specific keywords:

Priority levels - Use --priority to control log visibility by setting a priority level. This filters log output to show only the specified priority level, helping you focus on logs from your component or other processes.
- emerg - System is unusable, maps to:
  - APMF_LOG(…, FATAL)
- alert - Action must be taken immediately
- crit - Critical conditions, maps to:
  - LOG_F(FATAL)
  - LOG_S(FATAL)
- err - Error conditions, maps to:
  - APMF_LOG(…, ERROR)
  - LOG_F(ERROR)
  - LOG_S(ERROR)
  - console.error() (JavaScript)
- warning - Warning conditions, maps to:
  - APMF_LOG(…, WARNING)
  - LOG_F(WARNING)
  - LOG_S(WARNING)
  - console.warn() (JavaScript)
- notice - Normal but significant conditions
- info - Informational messages, maps to:
  - APMF_LOG(…, INFO)
  - LOG_F(INFO)
  - LOG_S(INFO)
  - console.log() (JavaScript)
- debug - Debug-level messages, maps to:
  - APMF_LOG(…, DEBUG)
  - LOG_F(DEBUG)
  - LOG_S(DEBUG)

Time specifications - Filter logs by time using --since or --until:

Keywords: now, yesterday, today, and tomorrow

Time format:

%Y.%b.%dT%H:%M:%S    (2024.12.21T16:00:59)
%Y.%b.%dT%H:%M       (2024.12.21T16:00)
%Y.%m.%dT%H:%M:%S    (2024.Dec.21T16:00:59)
%Y.%m.%dT%H:%M       (2024.Dec.21T16:00)
%H:%M:%S             (16:00:59)
%H:%M                (16:00)

Output format using --output-format: a. short_concise (Default)

__REALTIME_TIMESTAMP _HOSTNAME SYSLOG_FACILITY.PRIORITY SYSLOG_IDENTIFIER[_PID]: TID MESSAGE

Example:

Nov 01 14:08:20.522382 amazon-8668d42631656f65 daemon.info smartboxd[1076]: 1076 I SmartBox:[run] watchdog service at 757064

b. short_precise

__REALTIME_TIMESTAMP _HOSTNAME SYSLOG_IDENTIFIER[_PID]: MESSAGE

Example:

Nov 01 14:59:49.134671 firestick-83f109b314d1eb9e smartboxd[872]: I SmartBox:[LogViewer] Opened

For Vega packages, LoggingCtl uses _CMDLINE instead of SYSLOG_IDENTIFIER to display the package URL origin. Use the -v (package ID) filter for the most reliable filtering of your app’s logs. Example:

System service log
Nov 01 14:59:49.134671 firestick-83f109b314d1eb9e smartboxd[872]: I SmartBox:[LogViewer] Opened

Vega package log
Nov 01 15:17:39.279675 firestick-83f109b314d1eb9e local0.debug com.amazon.dev.shell:dev_shell_app[2617]: 2 D base-monitor-loop:[BaseMonitoredAsyncLoop.cpp:53] Scheduling new idle work

Vault commands

Use loggingctl vault commands to manage and access the smartboxd vault system.

$ loggingctl vault
Vault commands - query logging and crash data archived on device

Usage: loggingctl vault [OPTIONS]

Options:
  --flush                                                           Force artifact enrollment
  --upload <uploadType>                                             Upload logs/crashes
  --purge <artifactType>                                            Remove artifacts
  --get-index <type> <client>                                       Get client index
  --set-index <type> <client> <index>                               Set client index
  --last-index <artifactType>                                       Get last index
  --get-index-stats                                                 Print index statistics
  --config                                                          Show path configurations
  --storage [<artifactType>]                                        View storage usage
  --enroll <tag> <fileName> <data> [<zero-content>] [<zero-meta>]   Manual artifact enrollment
  --health-check                                                    System health verification
  --cat <type> <index>                                              View vault contents
  --ls [<artifactType>]                                             List artifacts
  --json-dump <type>                                                Export metadata as JSON
  --size <type> <index>                                             Show artifact size
  -h, --help                                                        Print help

Access crash reports (ACR files)

Use vault commands to list and retrieve crash report files (ACR) stored on the device. For background on ACR files and how to symbolicate them, see Symbolicate App Crash Reports.

List available ACR files

To see all ACR files on the device:

$ loggingctl vault --ls SYSTEM_TOMBSTONE/acr

Output shows filenames in the format :

{
 "artifacts": [
  "91#crash_1776695212_30024_5000_1328_11_com_example_myapp.acr",
  "90#crash_1776688049_30024_5000_2794_11_com_example_videoplayer.acr",
  "18#crash_1776688021_106_106_1055_6_-usr-bin-location-service.acr",
  "31#crash_1776688021_101_101_1219_6_-usr-bin-eventmgrd.acr",
  ...
 ],
 "status": 0
}

The number before # is the index used to retrieve the file. The filename encodes:

Field	Description
Index	Number before `#`, used with `--cat` to retrieve the file
Timestamp	Unix epoch when the crash occurred
UID/GID	User and group ID of the crashed process
PID	Process ID
Signal	Signal number (6=SIGABRT, 11=SIGSEGV, 3=SIGQUIT, 4=SIGILL)
Binary	Package name or binary path

Get ACR metadata

To get detailed metadata for all ACR files as JSON:

$ loggingctl vault --json-dump SYSTEM_TOMBSTONE/acr

{
  "acr": {
    "PathInVault": "/var/lib/data/ace/dropbox/vault/SYSTEM_TOMBSTONE/acr",
    "artifacts": [
      {
        "age": "1776688374",
        "filename": "91#crash_1776695212_30024_5000_1328_11_com_example_myapp.acr",
        "filepath": "/var/lib/data/ace/dropbox/vault/SYSTEM_TOMBSTONE/acr/91#...",
        "importance": "100",
        "size": "731573"
      }
    ],
    "storage": "26057639"
  },
  "status": 0
}

Get the most recent crash index

$ loggingctl vault --last-index SYSTEM_TOMBSTONE

{
 "index": 91,
 "status": 0
}

Check ACR file size

$ loggingctl vault --size SYSTEM_TOMBSTONE <index>

{
 "index": 18,
 "size": 127875,
 "status": 0,
 "tag": "SYSTEM_TOMBSTONE"
}

Retrieve an ACR file

Use --cat with the artifact type SYSTEM_TOMBSTONE and the index number:

$ loggingctl vault --cat SYSTEM_TOMBSTONE <index>

This outputs the raw ACR file content to stdout.

Save an ACR file

To save an ACR file to the device filesystem, redirect the output of --cat:

$ loggingctl vault --cat SYSTEM_TOMBSTONE <index> > crash_report.acr

Example: retrieve a crash report

# List your application's crash reports
$ loggingctl vault --ls SYSTEM_TOMBSTONE/acr
{
 "artifacts": [
  "91#crash_1776692263_30024_5000_1296_11_com_example_myapp.acr",
  "85#crash_1776688021_30024_5000_1219_6_com_example_myapp.acr",
  "72#crash_1776687973_30024_5000_1055_11_com_example_myapp.acr"
 ],
 "status": 0
}

# Save one by its index
$ loggingctl vault --cat SYSTEM_TOMBSTONE 91 > crash_report.acr

Command reference for ACR access

Command	Artifact type argument	Description
`--ls SYSTEM_TOMBSTONE/acr`	`SYSTEM_TOMBSTONE/acr`	List all ACR filenames with indices
`--json-dump SYSTEM_TOMBSTONE/acr`	`SYSTEM_TOMBSTONE/acr`	Get detailed JSON metadata
`--last-index SYSTEM_TOMBSTONE`	`SYSTEM_TOMBSTONE`	Get the most recent index
`SYSTEM_TOMBSTONE`	Check file size before downloading
`SYSTEM_TOMBSTONE`	Retrieve file content

Permission structure

LoggingCtl implements role-based access control through default and component shell permissions. When operating in default or component shell mode, you can access:

Index operations to track and manage log indices:
- --last-index - View the most recent log entry index
- --get-index-stats - Get statistics about current log indices
Content access to view logs using --cat for:
- Your component-specific logs
- Sideloaded package logs
- System processes: stemd, lcm_service, inputd, and related services
Listing operations to view artifact information using the following commands:
- --ls - Lists available logs
- --json-dump - Exports metadata
- --size - Checks artifact file sizes
- --storage - Checks total vault storage or specific artifact storage

All listing operations work with main, system, SYSTEM_TOMBSTONE, and ACR_REPORT.

Access denied

When you attempt unauthorized operations or try to access privileged data, you see a denied response:

{
    "error": "Insufficient permissions",
    "status": -7
}

Log access restrictions

LoggingCtl limits access to the following log types:

Sideloaded component logs
Daemon facility logs
System components, including stemd, acr_core_dump, lcm_service, servicergrd, pkgmgrd, and inputd

​Start or restart LoggingCtl after installing new apps

​Basic usage

​Configuration commands

​Reset configuration

​Log budget and suppression

​Detect suppression

​Reduce dropped lines

​Log commands

​Recommended filtering to view logs

​JavaScript logging considerations

​Supported argument keywords

​Vault commands

​Access crash reports (ACR files)

​List available ACR files

​Get ACR metadata

​Get the most recent crash index

​Check ACR file size

​Retrieve an ACR file

​Save an ACR file

​Example: retrieve a crash report

​Command reference for ACR access

​Permission structure

​Access denied

​Log access restrictions

​Related topics