Difference between revisions of "Android Logging System"

From eLinux.org
Jump to: navigation, search
(Overview)
m (Overview: minor typos)
 
(13 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
This article describes the Android logging system
 
This article describes the Android logging system
 +
 
== Overview ==
 
== Overview ==
The Android system has a logging facility that allows systemwide logging of information, from applications and system components.
+
The Android system has a logging facility that allows system-wide logging of information, from applications and system components.
 
This is separate from the Linux kernel's own logging system, which is accessed using 'dmesg' or '/proc/kmsg'.  However, the logging system does store messages in kernel buffers.
 
This is separate from the Linux kernel's own logging system, which is accessed using 'dmesg' or '/proc/kmsg'.  However, the logging system does store messages in kernel buffers.
 +
 +
[[image:Android-logging-kmc-kobayashi.png|right|frame|image by Tetsuyuki Kobabayshi, of Kyoto Microcomputer Co.]]
  
 
The logging system consists of:
 
The logging system consists of:
Line 16: Line 19:
 
* main - the main application log
 
* main - the main application log
 
* events - for system event information
 
* events - for system event information
* radio - for radio and phone-related informatio
+
* radio - for radio and phone-related information
 
* system - a log for low-level system messages and debugging
 
* system - a log for low-level system messages and debugging
  
Line 22: Line 25:
 
buffer (outside of '/dev/log/main') so that a single verbose application couldn't overrun system messages
 
buffer (outside of '/dev/log/main') so that a single verbose application couldn't overrun system messages
 
and cause them to be lost.
 
and cause them to be lost.
 +
 +
Each message in the log consists of a tag indicating the part of the system or application that the message came from,
 +
a timestamp, the message log level (or ''priority'' of the event represented by the message) and the log message itself.
 +
 +
All of the log buffers except for 'event' use free-form text messages.  The 'event' buffer is a 'binary' buffer,
 +
where the event messages (and event parameters) are stored in binary form.  This form is more compact, but requires
 +
extra processing when the event is read from the buffer, as well as a message lookup database, to decode the event strings.
 +
 +
The logging system automatically routes messages with specific tags into the radio buffer.  Other messages are placed
 +
into their respective buffers when the the log class or library for that buffer is used.
  
 
== Kernel driver ==
 
== Kernel driver ==
 
The kernel driver for logging is called the 'logger'. See [[Android logger]]
 
The kernel driver for logging is called the 'logger'. See [[Android logger]]
 +
 +
== System and Application logging ==
 +
=== Application log ===
 +
An Android application includes the [http://developer.android.com/reference/android/util/Log.html android.util.Log class], and uses methods of this class to write messages of different priority into the log.
 +
 +
Java classes declare their tag statically as a string, which they pass to the log method.  The log method used indicates the message "severity" (or log level).  Messages can be filtered by tag or priority when the logs are processed by retrieval tools (logcat).
 +
 +
=== Event log ===
 +
Event logs messages are created using [http://developer.android.com/reference/android/util/EventLog.html android.util.EventLog class], which create binary-formatted log messages.  Log entries consist of binary tag codes, followed by binary parameters.  The message tag codes are stored on the system at: /system/etc/event-log-tags.  Each message has the string for the log message, as well as codes indicating the values associated with (stored with) that entry.
 +
 +
=== System log ===
 +
Many classes in the Android framework utilize the system log to keep their messages separate from (possibly noisy) application log messages.  These programs use the android.util.Slog class, with its associated messages.
 +
 +
In all cases, eventually a formatted message is delivered through the C/C++ library down to the kernel driver, which stores the message in the appropriate buffer.
 +
 +
== 'log' command line tool ==
 +
There is a 'log' command line tool that can be used to create log entries from
 +
any program.  This is built into the 'toolbox' multi-function program.
 +
 +
The usage for this is:
 +
 +
USAGE: log [-p priorityChar] [-t tag] message
 +
        priorityChar should be one of:
 +
                v,d,i,w,e
 +
 +
== Capturing stdout with logwrapper ==
 +
It is sometimes useful to capture stdout from native applications into the log.  There is a utility called
 +
'logwrapper' which can be used to run a program, and redirect it's stdout into log messages.
 +
 +
The logwrapper usage is:
 +
Usage: logwrapper [-x] BINARY [ARGS ...]
 +
 +
Forks and executes BINARY ARGS, redirecting stdout and stderr to
 +
the Android logging system. Tag is set to BINARY, priority is
 +
always LOG_INFO.
 +
 +
-x: Causes logwrapper to SIGSEGV when BINARY terminates
 +
    fault address is set to the status of wait()
 +
 +
Source for logwrapper is at: system/core/logwrapper/logwrapper.c
  
 
== Logcat command ==
 
== Logcat command ==
Line 34: Line 87:
  
 
Some quick notes:
 
Some quick notes:
* Log messages each have a tag and log level.
+
* Log messages each have a tag and priority.
 
** You can filter the messages by tag and log level, with a different level per tag.
 
** You can filter the messages by tag and log level, with a different level per tag.
 
* You can specify (using a system property) that various programs emit their stdout or stderr to the log.
 
* You can specify (using a system property) that various programs emit their stdout or stderr to the log.
 +
 +
=== Trick to couple Android logging to Linux kernel logging ===
 +
Note that the android logging system is completely separate from
 +
the Linux kernel log system (which uses printk inside the kernel
 +
to save messages and dmesg to extract them).  You can write to
 +
the kernel log from user space by writing to /dev/kmsg.
 +
 +
I've seen a reference to couple the two together, to redirect
 +
android messages into the kernel log buffer, using the 'logcat'
 +
program launched from init, like below:
 +
 +
service logcat /system/bin/logcat -f /dev/kmsg
 +
      oneshot
 +
 +
(See http://groups.google.com/group/android-kernel/browse_thread/thread/87d929863ce7c29e/f8b0da9ed6376b2f?pli=1)
 +
 +
I'm not sure why you'd want to do this (maybe to put all messages into a
 +
single stream?  With the same timestamp, if kernel message timestamping is on?)
  
 
== Resources ==
 
== Resources ==
 +
* [http://developer.android.com/guide/developing/tools/adb.html Android Debug Bridge reference page] - has 'adb logcat' usage information
 +
* [http://blog.kmckk.com/archives/2936958.html Logging System Of Android] Presentation by Tetsuyuki Kobayashi, September, 2010 at CELF's [[Japan Technical Jamboree 34]]
 +
 +
[[Category:Android]]

Latest revision as of 02:09, 24 July 2015

This article describes the Android logging system

Overview

The Android system has a logging facility that allows system-wide logging of information, from applications and system components. This is separate from the Linux kernel's own logging system, which is accessed using 'dmesg' or '/proc/kmsg'. However, the logging system does store messages in kernel buffers.

image by Tetsuyuki Kobabayshi, of Kyoto Microcomputer Co.

The logging system consists of:

  • a kernel driver and kernel buffers for storing log messages
  • C, C++ and Java classes for making log entries and for accessing the log messages
  • a standalone program for viewing log messages (logcat)
  • ability to view and filter the log messages from the host machine (via eclipse or ddms)

There are four different log buffers in the Linux kernel, which provide logging for different parts of the system. Access to the different buffers is via device nodes in the file system, in /dev/log.

The four log buffers are:

  • main - the main application log
  • events - for system event information
  • radio - for radio and phone-related information
  • system - a log for low-level system messages and debugging

Up until 2010, only the first three logs existed. The system log was created to keep system messages in a separate buffer (outside of '/dev/log/main') so that a single verbose application couldn't overrun system messages and cause them to be lost.

Each message in the log consists of a tag indicating the part of the system or application that the message came from, a timestamp, the message log level (or priority of the event represented by the message) and the log message itself.

All of the log buffers except for 'event' use free-form text messages. The 'event' buffer is a 'binary' buffer, where the event messages (and event parameters) are stored in binary form. This form is more compact, but requires extra processing when the event is read from the buffer, as well as a message lookup database, to decode the event strings.

The logging system automatically routes messages with specific tags into the radio buffer. Other messages are placed into their respective buffers when the the log class or library for that buffer is used.

Kernel driver

The kernel driver for logging is called the 'logger'. See Android logger

System and Application logging

Application log

An Android application includes the android.util.Log class, and uses methods of this class to write messages of different priority into the log.

Java classes declare their tag statically as a string, which they pass to the log method. The log method used indicates the message "severity" (or log level). Messages can be filtered by tag or priority when the logs are processed by retrieval tools (logcat).

Event log

Event logs messages are created using android.util.EventLog class, which create binary-formatted log messages. Log entries consist of binary tag codes, followed by binary parameters. The message tag codes are stored on the system at: /system/etc/event-log-tags. Each message has the string for the log message, as well as codes indicating the values associated with (stored with) that entry.

System log

Many classes in the Android framework utilize the system log to keep their messages separate from (possibly noisy) application log messages. These programs use the android.util.Slog class, with its associated messages.

In all cases, eventually a formatted message is delivered through the C/C++ library down to the kernel driver, which stores the message in the appropriate buffer.

'log' command line tool

There is a 'log' command line tool that can be used to create log entries from any program. This is built into the 'toolbox' multi-function program.

The usage for this is:

USAGE: log [-p priorityChar] [-t tag] message
       priorityChar should be one of:
               v,d,i,w,e

Capturing stdout with logwrapper

It is sometimes useful to capture stdout from native applications into the log. There is a utility called 'logwrapper' which can be used to run a program, and redirect it's stdout into log messages.

The logwrapper usage is:

Usage: logwrapper [-x] BINARY [ARGS ...]

Forks and executes BINARY ARGS, redirecting stdout and stderr to
the Android logging system. Tag is set to BINARY, priority is
always LOG_INFO.

-x: Causes logwrapper to SIGSEGV when BINARY terminates
    fault address is set to the status of wait()

Source for logwrapper is at: system/core/logwrapper/logwrapper.c

Logcat command

You can use the 'logcat' command to read the log. This command is located in /system/bin in the local filesystem, or you can access the functionality using the 'adb logcat' command.

Documentation on the use of this command is at: http://developer.android.com/guide/developing/tools/adb.html

Some quick notes:

  • Log messages each have a tag and priority.
    • You can filter the messages by tag and log level, with a different level per tag.
  • You can specify (using a system property) that various programs emit their stdout or stderr to the log.

Trick to couple Android logging to Linux kernel logging

Note that the android logging system is completely separate from the Linux kernel log system (which uses printk inside the kernel to save messages and dmesg to extract them). You can write to the kernel log from user space by writing to /dev/kmsg.

I've seen a reference to couple the two together, to redirect android messages into the kernel log buffer, using the 'logcat' program launched from init, like below:

service logcat /system/bin/logcat -f /dev/kmsg 
      oneshot

(See http://groups.google.com/group/android-kernel/browse_thread/thread/87d929863ce7c29e/f8b0da9ed6376b2f?pli=1)

I'm not sure why you'd want to do this (maybe to put all messages into a single stream? With the same timestamp, if kernel message timestamping is on?)

Resources