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. To access the loggingctl command, you must enter the Vega device shell using the kepler 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 configuration 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: Restart the logging service:
systemctl restart systemd-journald

Log commands

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

If logs don’t appear for your app:

Install the app manually:
vda shell vpm install <app>
Start LoggingCtl:
vega exec vda shell loggingctl log -f
Start the app:
vda shell vmsgr send

JavaScript logging considerations

When using JavaScript logging in your Kepler 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.error() (JavaScript)
- notice - Normal but significant conditions
- info - Informational messages, maps to:
  - APMF_LOG(…, INFO)
  - LOG_F(INFO)
  - LOG_S(INFO)
  - console.error() (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

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

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

​Permission structure

​Access denied

​Log access restrictions

​Related topics