Logger Settings

Overview

The Settings screen provides controls for defining the logging behavior. It can be reached from the main screen by tapping on the Settings icon.

The screen operates similar to the Android Settings application. The settings are organized into groups, and the first screen displays a summary value of each group. Tapping on the name of a group will take you to a screen with additional controls related to that group. For each log module, the entire module can be turned on/off directly by tapping the switch to the right of its name.

EMM Configuration

The configuration settings available from the Settings screen can also be managed by Scan2Deploy Studio or an EMM console. Once the values have been sent to the device, they will take precedence over values that may have been set within the app from the Settings screen.

Once an EMM configuration has been applied, the first settings screen will display an additional switch labeled Override administrator settings. When this switch is disabled, the controls in the configuration Settings screen are disabled to prevent settings adjustments from the device. When enabled, the EMM settings are ignored and the controls are enabled to allow the settings to be changed.

General Settings

This settings group controls general logging behavior. The following settings are available:

Setting	Description
Archive server URL	This specifies the URL of the server which can receive archive files. If any basic authentication (username and password) is required, include this in the URL. To archive files to the SD card, leave this setting blank.
Start logging on boot	If enabled, logging will automatically start when the device boots.

Server URL support

Multiple transfer protocols are supported when specifying the URL to upload archive files to. Supported protocols include: HTTP, HTTPS, FTP and FTPS. All protocols support basic authentication (username and password), and TLS v1.3.

When uploading a file over HTTP, Logger will issue a POST command to an endpoint constructed by adding the archive filename to the end of the URL in the configuration setting (which does not need to include a final slash '/'). The POST request will contain the following characteristics:

Field	Contents
Content-Type	Set to "application/zip".
Request Data	Contains the entire contents of the archive ZIP file (in raw binary).

Here are some example URLs, and the generated Logger network action for an archive file named archive.zip:

• https://www.logserver.com/logs: This will issue a POST to https://www.logserver.com/logs/archive.zip
• ftp://user:1234@www.logftp.com/crash/logs: This will send the file to the FTP server www.logftp.com using the login of "user" with the password "1234" and place it in the directory "crash/logs".

Logcat Settings

Logcat is a tool that logs messages from the Android system. It also logs stack traces when an application throws an error, as well as other messages it writes. This module has the following settings available:

Setting	Description
Enable Logcat	Includes Logcat content in the log archive.
Log file size limit	Maximum size (in MB) allowed for storing Logcat content. It does not impact other log modules. If the limit is reached, the oldest log entries will be discarded to make room for new ones. This is used to prevent the entire storage capacity of the device from being consumed by a log file.
Logcat groups
Enable Main group	Includes Logcat entries belonging to the Main group.
Enable Crash group	Includes Logcat entries belonging to the Crash group.
Enable System group	Includes Logcat entries belonging to the System group.
Enable Event group	Includes Logcat entries belonging to the Event group.
Enable Radio group	Includes Logcat entries belonging to the Radio group.
Logcat log contents
Timestamp	Log entries will include the date/time when the entry was created.
Process/Thread IDs	Log entries will include (system assigned) process and thread IDs of the software that created them.
Package name	Log entries will include the package name of the software that created them.
Tag	Log entries will include the tag assigned by software when they are created. This can be useful for identifying related information.
Package filter	This is the list of which package names in log entries are included. All other entries are discarded. If empty, log entries for all packages are included. See the following section for details.
Tag filter	This is an expression which defines which log entries are included. All other entries are discarded. If empty, all log entries are included. See the following section for details.

Creating a Filter

Disabling Logcat groups is a way to reduce the volume of log entries by limiting the content to only certain groups. More precise control can be used by creating package and tag filters. These filters are used in addition to the group enable settings.

A package filter is made from a list of package names, separated from each other by a space. Each name indicates one of the package names required for tag entries that are reported. If blank, no tag entries are excluded due to the package name.

A tag filter is made from one or more filter expressions, separated from each other by a space. Each filter expression is defined as tag or tag:priority, where priority is optional and is a letter indicating the minimum priority reported for log entries with a matching tag. The priority options, listed from lowest to highest are:

• V Verbose
• D Debug
• I Information
• W Warning
• E Error
• F Fatal
• S Silent

When not specified in a filter, all priorities are included (same as Verbose). A special value of * may be used for tag in a filter expression to define the minimum priority reported for all tags not otherwise specified in a filter.

Tag Filter Examples

The results for the following example tag filters refer to these sample Logcat entries. Each entry shows the following information, in order: date (month, day), time (24-hour format), process ID, thread ID, package, priority, tag, message.

02-22 18:07:58.263 (29127: 2738)/com.dev.wms   V/BigJob: Starting transaction
02-22 18:08:40.041 ( 1652: 1699)/com.google.os D/ActivityMgr: activityStop
02-22 18:08:43.714 ( 1652: 2288)/com.google.os D/PowerMgr: lock=145488661 ws=null
02-22 18:08:44.714 ( 1652: 2288)/com.google.os W/PowerMgr: charging stopped
02-22 18:09:01.582 (29127: 2738)/com.dev.wms   E/BigJob: Transaction failed

Filter(s)	Result
Package: com.dev.wms Tag: Empty	This will only include lines with the package name "com.dev.wms". (Keep the first and last entries.)
Package: com.dev.wms Tag: *:E	This will only include lines with the package name "com.dev.wms", and a priority of at least Debug. (For the example, this will only include the last entry.)
Package: Empty Tag: BigJob:V *:S	This will only include lines with the "BigJob" tag. (Keep the first and last entries.)
Package: Empty Tag: BigJob:S	This will exclude lines with the "BigJob" tag. (Discard the first and last entries.)
Package: Empty Tag: BigJob:W	This will exclude lines with the "BigJob" tag which are not at least Warning priority level. (For the example, this will remove only the first entry. Entries 2-4 are not affected, since the tag doesn't match.)
Package: Empty Tag: *:W	This will only include lines with a priority of at least Warning. (For the example, this will only include the last two entries.)

Kernel Settings

The Kernel module manages log messages generated by operating system device drivers. It has the following settings available:

Setting	Description
Enable Kernel	If enabled, Kernel content will be included in the log archive.
Log file size limit	Maximum size (in MB) allowed for storing Kernel content. It does not impact other log modules. If the limit is reached, the oldest log entries will be discarded to make room for new ones. This is used to prevent the entire storage capacity of the device from being consumed by a log file.
Kernel log contents
Timestamp	Log entries will include the date/time when the entry was created.
Level of detail	Specifies the maximum log level allowed for included entries. All other entries are discarded. The log levels (in increasing order) are: Emergency Alert Critical Error Warning Notice Information Debug For example: A setting of Alert will allow Emergency and Alert entries, but discard Notice entries.

Reset Settings

Tapping on Reset settings in the initial settings screen will reset all the logging behavior settings to default values. Here is a list of all the settings and their default values.

Setting	Default value
General
Archive server URL	Clear (Send to external SD card)
Start logging on boot	Disabled
Logcat
Enable Logcat	Enabled
Log file size limit	10 MB
Logcat groups
Enable Main group	Enabled
Enable Crash group	Enabled
Enable System group	Disabled
Enable Event group	Disabled
Enable Radio group	Disabled
Logcat log contents
Timestamp	Enabled
Process/Thread IDs	Disabled
Package name	Enabled
Tag	Enabled
Package filter	Not set (Content is not filtered.)
Tag filter	Not set (Content is not filtered.)
Kernel
Enable Kernel	Enabled
Log file size limit	10 MB
Kernel log contents
Timestamp	Enabled
Level of detail	Warning

Suggested Use

In an ideal world, logging could be performed by collecting all possible information so that nothing potentially interesting would be lost. The storage limits of the device make this impractical, so some limits must be placed on what information is recorded in a log archive. Here are some suggestions for making best use of the filters.

• The best limits to use are likely not known when first capturing logs. Begin with slightly relaxed filters (more Logcat groups, no tag filters, higher kernel levels).

• After reviewing the first few logs, slowly add more filters to eliminate unhelpful content. For example, add a tag filter Power:* if entries with a tag of "Power" appear to be unrelated to the issue. You could also add a package filter such as "com.vendor.myapp" to only include messages coming from a specific application. Additionally, disable Logcat groups which do not contain useful content.

• It is important to stop logging soon after an problem begins. If you don't, the logs may fill with additional entries and force the relevant information to be discarded due to lack of space. If this proves difficult to do, then consider increasing the log size limit or use additional filtering to make more effective use of the size limit.

• Care should be taken to avoid allowing the log files to consume too much storage. If the size is too large, then it might prevent the customer application from being able to store its own data on the device (and thereby fail). The default values should generally be sufficient for most situations.