Understand logging

This article covers the process of logging, including log standards, level guidelines, classes, purposes, and multistack approximations.

Log standards

Logging in Android is complex due to the mix of standards used that are combined in logcat. The main standards used are detailed below:

Figure 1: Log level standards.

Though each of these standards have similar level construction, they vary in granularity. Approximate equivalents across the standards are as follows:

Figure 2: syslog, Android, and Java logging levels.

Log level guidelines

There are existing guidelines given for each log standard. The chosen log level follows the appropriate standard being used, like using the syslog standard for kernel development.

Log level orders, from least-to-most, are shown in the three figures below:

Figure 3: android.util.Log

Figure 4: java.util.Logging.Level.

Figure 5: RFC 5424 - Section 6.2.1.

App logging

Selective logging is performed with TAG by android.util.Log class using Log#isLoggable, as shown below:

if (Log.isLoggable("FOO_TAG", Log.VERBOSE)) {
 Log.v("FOO_TAG", "Message for logging.");
}

Logs can be tuned at runtime to provide a select level of logging as shown below:

adb shell setprop log.tag.FOO_TAG VERBOSE

log.tag.* properties are reset on reboot. There are persistent variants that remain across reboots as well. See below:

adb shell setprop persist.log.tag.FOO_TAG VERBOSE

Log#isLoggable checks leave log traces in the app code. Boolean DEBUG flags bypass log traces using compiler optimizations that are set to false, as shown below:

private final static boolean DEBUG = false;


…
If (DEBUG) {
 Log.v("FOO_TAG", "Extra debug logging.");
}

Logging can be removed on a per-APK basis via ProGuard rulesets by R8 at compile time. The following example removes everything below INFO level logging for android.util.Log:

# This allows proguard to strip isLoggable() blocks containing only <=INFO log
# code from release builds.
-assumenosideeffects class android.util.Log {
  static *** i(...);
  static *** d(...);
  static *** v(...);
  static *** isLoggable(...);
}
-maximumremovedandroidloglevel 4

This is useful for handling multiple app build types (for example, development builds vs. release builds) where the underlying code is expected to be the same, but the allowed log levels are different. An explicit policy must be set and followed for apps (particularly system apps) to decide how build types and release expectations impact log output.

System logging in the Android Runtime (ART)

There are several available classes that are available for system apps and services:

Figure 6: Available system log classes and purposes.

Though android.util.Log and android.util.Slog use the same log level standards, Slog is an @hide class usable only by the platform. The EventLog levels are mapped to the entries in the event.logtags file in /system/etc/event-log-tags.

Native logging

Logging in C/C++ follows the syslog standard with syslog(2) corresponding to the Linux kernel syslog that controls the printk buffer, and syslog(3) corresponding to the general system logger. Android uses the liblog library for general system logging.

liblog provides wrappers for the sublogs groups using the following macro form:

RLOGD, for example, corresponds to [Radio log buffer ID] LOG [Debug Level]. The major liblog wrappers are as follows:

Figure 7: liblog wrappers.

Android has higher level interfaces for logging that are favoured over direct liblog usage, as seen below:

Figure 8: Higher level log Libraries.

Multistack approximations

Due to differences in granularity and level intent, there are no clear or exact matchings of different logging standards. For example, the java.util.logging.Level and android.util.Log levels for error logs are not a 1:1 match:

Figure 9: Error level in standard Java logging vs. Android logging.

In cases like this, use the individual standard to determine which level to apply.

During system development with multiple stack level components, follow Figure 1 to determine which standard to use per-component. For an approximate guide to tier messaging, follow Figure 2.

Security and privacy

Do not log Personally Identifiable Information (PII). This includes details such as:

• Email addresses
• Telephone numbers
• Names

Similarly, certain details are considered sensitive even if not explicitly personally identifiable.

For example, though timezone info is not considered personally identifiable, it does give an indication of the approximate location of a user.

Log policy and acceptable details must be handled as part of security and privacy review before release.

Device logs

Access to all device logs, including using android.permission.READ_LOGS is restricted:

• If an app in the background requests access to all device logs, the request is automatically denied unless the app:
• Shares the system UID.
• Uses a native system process (UID < APP_UID).
• Uses DropBoxManager.
• Accesses only the event log buffer.
• Uses the EventLog API.
• Uses instrumented tests.
• If an app in the foreground with READ_LOGS requests access to device logs, the system prompts the user to approve or deny the access request.