Incident Logging

In order to provide helpful data about how JavaRosa is being used in the Field, the core system provides instrumentation for an Incident Log. The log can be used to record important usage patterns and potentially when user errors occur.

The incident log is platform agnostic, and must have an implementation registered for any of the platforms which wish to use it. For J2MERosa, this implementation is provided in the J2MEModule automatically.

'''NOTE - The incident log is _not_ an dump for every piece of output for debugging and error handling. It is intended to be used to capture and analyze usage patterns and usability data, and this purpose will be severely hampered if it is full of redirected stdout calls and carelessly dumped stack traces.'''

Logging Incidents

Incidents can be logged through the service provider with the JavaRosaServiceProvider.instance().logIncident method. The method takes two arguments

• '''Type''' : The type of incident which has occurred, a few different default types are statically available in the IncidentLog class. The type is available for everything that serializes incidents, and is useful to group categorically incidents which should be analyzed together, like "Activity Launches"
• '''Message''' : A message describing the incident, like "User Canceled Patient Edit".

By default, these pieces of data, along with the date of the logging call, are recorded.

Managing the Logs

Incident data can be managed generically through the JavaRosaServiceProvider's getIncidentLogger property. There are three general functions available,

• '''Clear''' : Clears all underlying log data.
• '''Log''' : Logs an Incident
• '''Serialize''' : Serializes the incident log into the format specified by the provided serializer. A general FlatLogSerializer is provided with the core. Serialized data is not cleared afterward by default, so be sure to clear the log after serialization if you don't want it to build up.

The Logging can be enabled or disabled at will with the JavaRosa core property JavaRosaPropertyRules.LOGS_ENABLED, which will show up in the j2me settings screen as long as the other default JavaRosaPropertyRules have been registered. It is disabled by default, so you should enable it in your property initialization if logging should be enabled.

The J2ME Incident Log

The J2ME incident log, included automatically with the module inclusion J2MEModule.registerModule, is an RMS backed incident log implementation. It should be managed using the generic behaviors with the JavaRosaServiceProvider discussed above, and can be enabled/disabled in generic manner.

In addition to the implementation, the org.javarosa.log project contains a useful management activity that can be launched to provide a user interface for dealing with logs. The activity will allow the logs to be cleared, viewed on the phone, or sent off the phone as a flat text file. In order to send data off the phone, the LogManagementModule should be registered, and the appropriate Properties should be set for the desired destination of the serialized logs.