Request For Comment

Eclipse Platform Core RFC 0003

Log File Retrieval

Summary
There is a requirement to make available programatically the information that has been written to the platform log file. This RFC describes the proposed approach, which involves adding a new API method for obtaining the log file location, and changing the log file format to XML.
By John Arthorne, OTI.
Created: 28-NOV-2001.
Modified 3-JAN-2002. Removed API method for log retrieval.
Modified 5-DEC-2001. Sample log file added.

The Problem

Currently, the only way to programatically access the platform log is by adding a listener by calling Platform.addLogListener(ILogListener). While this approach has many benefits, there are also some drawbacks:

If errors or warnings occur during platform startup, before listeners can be added, it is impossible to programatically obtain information about these errors. It is even impossible to detect if startup errors have occurred.
A listener has no access to errors that have been logged before that listener was activated. Since plug-ins cannot control when they are started, they may miss logged information that is interesting to them.
Each listener that wants to maintain a representation of what has been logged must keep their own list. This leads to a duplication of the information available in the log file on disk.

The Solution

The proposed solution is to add an API method to org.eclipse.core.runtime.Platform that returns the location of the log file, and to make the log file an XML file with a known DTD. With a well known log file name and format, third parties can use Xerces to scan or parse the log file to retrieve the information they are interested in. The proposed API method is:

/**
 * Returns the location of the platform log file.  This file may contain information
 * about errors that have previously occurred during this invocation of the Platform.
 * @return the path of the log file on disk.
 */
IPath getLogFileLocation();

The proposed document type definition for the log file is provided below. This format will be considered API.

<!ELEMENT log (entry)*>

<!ELEMENT entry (status)>
<!ATTLIST entry
date CDATA #REQUIRED>

date - the date this entry was logged, in the default java date format.

<!ELEMENT status (status)* (exception)?>
<!ATTLIST status
    sev (ERROR | INFO | OK | WARNING) #REQUIRED
    id CDATA #REQUIRED
    code CDATA #REQUIRED
    msg CDATA #REQUIRED>

sev - the problem severity.
id - the ID of the plug-in in which the error occurred.
code - the error code, an integer value that generally has some meaning for the plug-in that generated the error. See org.eclipse.core.runtime.IStatus#getCode.
msg - the status message, describing the error that occurred.

<!ELEMENT exception (exception)? >
<!ATTLIST exception
msg CDATA #REQUIRED
trace CDATA #REQUIRED>

msg - the message associated with some java.lang.Throwable object.
trace - a stack trace provided by java.lang.Throwable#printStackTrace.

The log file would remain at its present location, and its name would remain the same (.log). Here is a sample log file in the new XML format.

RFC Status

This proposal has been accepted, implemented, and released in build 20020409.