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: Set the rate back to the default value (1000):
loggingctl config --set-rate <PROCESS> 1000

For log levels: Set the level back to the default (info):
loggingctl config --set-level <PROCESS> info
To apply changes system-wide (required after changing rate or level): Restart the logging service:
systemctl restart systemd-journald

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 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