Androlog reporting

Androlog provides a simple reporting framework (1.0.1+). This reporting framework send useful reports:

• containing logged messages and stack traces
• information about the application (version, code) and the device (model)
• to several endpoints (HTTP POST, Mail ...)

This page explains how to configure the reporting.

Basics

The Androlog reporting support aims to tackle the limitation of the Android reports. First, reports contain more data and in particular the logged messages. The reporting is completely configurable especially how is sent the report.

Reports are triggered:

• using Log.report methods (report sent asynchronously).
• when a message from a specific level or higher is logged
• when an exception if not caught

Those possibilities gives a large spectrum of possibilities to send meaningful reports.

Configuration

To enable the reporting, the Androlog configuration file must be placed in the application's assets. In addition:

• Androlog must be initialized with the Android context (Log.init(Context)).
• The property file must contain androlog.report.active=true.
• The property file must specify the used reporters using the androlog.report.reporters property.

The androlog.report.active property is different from the androlog.active property. So, propagation of the log message can be disabled (androlog.activate=false) but reporting enabled.

The androlog.report.reporters property specify the reporters to use. A reporter will be used when a report is triggered. Androlog provides 3 reporters:

• de.akquinet.android.androlog.reporter.NoopReporter : do nothing
• de.akquinet.android.androlog.reporter.PostReporter : post the report using a HTTP Post action
• de.akquinet.android.androlog.reporter.MailReporter : mail the report

Further information about those reporters and how to provide your own reporter is given later.

Report Configuration

The reporting behavior can be configured using the following properties.

Property Name	Required	Default Value	Note
androlog.report.active	Yes to enable reporting	False	Enable the reporting support
androlog.report.reporters	Yes to enable reporting		Comma separated ist of reporters (identified using their class name)
androlog.report.log.items	No	25	The number of lg entries contained in the report
androlog.report.default.level	No	INFO	The minimum level of log entries contained in the report
androlog.report.trigger.level	No	ASSERT	The level of log entries triggering a report automatically
androlog.report.exception.handler	No	True	Enables / Disables the Androlog Uncaught Exception Handler, enabled by default. This handler triggers a report if an exception is not caught
androlog.report.exception.handler.propagation	No	True	Enables / Disables the propagation to the default uncaught exception handler. The propagation is enabled by default.

Moreover, each reporter can specified some other properties.

Reporter configuration

Androlog provides 3 reporters.

de.akquinet.android.androlog.reporter.NoopReporter

This reporter does simply nothing and ignore reports. It's just here for testing purpose.

de.akquinet.android.androlog.reporter.PostReporter

The Post reporter send the report to an endpoint using HTTP Post. This reporter requires the androlog.reporter.post.url property (in the Androlog configuration file) indicating the endpoint's url.

de.akquinet.android.androlog.reporter.MailReporter

The Mail reporter send the report by mail, using the android.intent.action.SEND action. This reporter requires the androlog.reporter.mail.address address indicating the to mail address.

Example of configuration

This section gives a couple of Androlog report configuration.

Post report to a specific URL

androlog.report.active=true
androlog.report.reporters=de.akquinet.android.androlog.reporter.PostReporter
androlog.reporter.post.url=http://androlog-reporter.appspot.com/androlog_reporter

Mail report to a specific Mail address

androlog.report.active=true
androlog.report.reporters=de.akquinet.android.androlog.reporter.MailReporter
[email protected]

Configure report content

androlog.report.active=true
androlog.report.reporters=de.akquinet.android.androlog.reporter.PostReporter
androlog.reporter.post.url=http://androlog-reporter.appspot.com/androlog_reporter
androlog.report.default.level=ERROR
androlog.report.log.items=10

Configure when the report are automatically sent

androlog.report.active=true
androlog.report.reporters=de.akquinet.android.androlog.reporter.PostReporter
androlog.reporter.post.url=http://androlog-reporter.appspot.com/androlog_reporter
androlog.report.default.level=WARN
androlog.report.log.items=40
androlog.report.trigger.level=ERROR

Configuring and Sending reports programmatically

You can configure the reporting using the API:

• Log.activateReporting() : activate the reporting
• Log.deactivateReporting() : deactivate the reporting
• Log.setDefaultReportLevel(int level) : set the log level of message contained in the report

You can also trigger the report manually:

• Log.report() : send a report (if the reporting is disabled or not correctly configured this method returns false, otherwise true).
• Log.report(String message, Throwable error) : send a report with the specific message and error (if the reporting is disabled or not correctly configured this method returns false, otherwise true).

Developing your own Reporter

You can develop your own reporter by creating a class implementing the de.akquinet.android.androlog.reporter.Reporter interface:

/**
 * Reporter Interface.
 * A Reporter sends a Report to a specific endpoint
 * (url, mail ...).
 * Reporter instances are created by {@link Log} according
 * to the {@link Log#ANDROLOG_REPORT_REPORTERS} configuration
 * property.
 */
public interface Reporter {

    /**
     * Configures the reporter.
     * Each reporter can define their own configuration properties.
     * @param configuration the Androlog configuration.
     */
    public abstract void configure(Properties configuration);

    /**
     * Asks the reporter to send the report.
     * @param context the Android context
     * @param message a message (optional)
     * @param error a error to attach to the report (optional)
     * @return <code>true</code> if the report was sent correctly,
     * <code>false</code> otherwise.
     */
    public abstract boolean send(Context context, String message, Throwable error);
}

You reporter get the Androlog configuration in the configure method and so can configure himself. When the application triggers the report, the send method is called. To create the report content, the reporter can use:

String report = new Report(context, mes, err).getReportAsJSON()
                    .toString();

Once done, just add the qualified class name of your Reporter implementation to the androlog.report.reporters property. The class must be accessible by your application (contained in the same APK).