android.util
Class EventLog

java.lang.Object
  android.util.EventLog

public class EventLog
extends Object

Dynamically defined (in terms of event types), space efficient (i.e. "tight") event logging to help instrument code for large scale stability and performance monitoring. Note that this class contains all static methods. This is done for efficiency reasons. Events for the event log are self-describing binary data structures. They start with a 20 byte header (generated automatically) which contains all of the following in order:

• Payload length: 2 bytes - length of the non-header portion
• Padding: 2 bytes - no meaning at this time
• Timestamp:
  • Seconds: 4 bytes - seconds since Epoch
  • Nanoseconds: 4 bytes - plus extra nanoseconds
• Process ID: 4 bytes - matching Process.myPid()
• Thread ID: 4 bytes - matching Process.myTid()

The above is followed by a payload, comprised of the following:

• Tag: 4 bytes - unique integer used to identify a particular event. This number is also used as a key to map to a string that can be displayed by log reading tools.
• Type: 1 byte - can be either INT, LONG, STRING, or LIST.
• Event log value: the size and format of which is one of:
  • INT: 4 bytes
  • LONG: 8 bytes
  • STRING:
    • Size of STRING: 4 bytes
    • The string: n bytes as specified in the size fields above.
  • LIST:
    • Num items: 1 byte
    • N value payloads, where N is the number of items specified above.
• '\n': 1 byte - an automatically generated newline, used to help detect and recover from log corruption and enable stansard unix tools like grep, tail and wc to operate on event logs.

Note that all output is done in the endian-ness of the device (as determined by ByteOrder.nativeOrder()).

Nested Class Summary

static class	EventLog.Event A previously logged event read from the logs.
static class	EventLog.List An immutable tuple used to log a heterogeneous set of loggable items.

Field Summary

static byte	INT
static byte	LIST
static byte	LONG
static byte	STRING

Constructor Summary

EventLog()

Method Summary

static void	readEvents(int[] tags, Collection<EventLog.Event> output) Read events from the log, filtered by type.
static int	writeEvent(int tag, EventLog.List list) Send an event log message.
static int	writeEvent(int tag, int value) Send an event log message.
static int	writeEvent(int tag, long value) Send an event log message.
static int	writeEvent(int tag, Object... list) Send an event log message.
static int	writeEvent(int tag, String str) Send an event log message.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

INT

public static final byte INT

See Also:

Constant Field Values

LONG

public static final byte LONG

See Also:

Constant Field Values

STRING

public static final byte STRING

See Also:

Constant Field Values

LIST

public static final byte LIST

See Also:

Constant Field Values

Constructor Detail

EventLog

public EventLog()

Method Detail

writeEvent

public static int writeEvent(int tag,
                             int value)

Send an event log message.

Parameters:

tag - An event identifer

value - A value to log

Returns:

The number of bytes written

writeEvent

public static int writeEvent(int tag,
                             long value)

Send an event log message.

Parameters:

tag - An event identifer

value - A value to log

Returns:

The number of bytes written

writeEvent

public static int writeEvent(int tag,
                             String str)

Send an event log message.

Parameters:

tag - An event identifer

str - A value to log

Returns:

The number of bytes written

writeEvent

public static int writeEvent(int tag,
                             EventLog.List list)

Send an event log message.

Parameters:

tag - An event identifer

list - A EventLog.List to log

Returns:

The number of bytes written

writeEvent

public static int writeEvent(int tag,
                             Object... list)

Send an event log message.

Parameters:

tag - An event identifer

list - A list of values to log

Returns:

The number of bytes written

readEvents

public static void readEvents(int[] tags,
                              Collection<EventLog.Event> output)
                       throws IOException

Read events from the log, filtered by type.

Parameters:

tags - to search for

output - container to add events into

Throws:

IOException - if something goes wrong reading events