API: Logging and Monitoring

Logging

Note that the local logging is designed for more technical debug purposes. For custom events with clearly defined semantics, use the Monitoring API instead.

las2peer provides a logging class for each service. This logger extends the java.util.logging.Logger class and can be configured through it's interface. The logging class can be instantiated/fetched using

Context.get().getLogger(this.getClass());

Furthermore, the logger for the main service class is also available using

serviceInstance.getLogger();

This is for example useful to log events in the onStart() and onStop() hooks.

Features

• By default the logger creates a log directory "./log/" and logs with log level FINEST to the default log file "log/las2peer.log".
• As mentioned the logger supports the Java native Log Levels. Please see Level.
• Log rotation is done. Currently it uses up to 10 files with max 1 MB each.
• Furthermore all logging output with INFO or higher is written to console (stderr). This way stdout is clean for developer defined output and the logging output may be filtered by system or external programs. Last but not least this is in compliance with the las2peer shell interactive mode.

Monitoring

Special Events can be logged and later analyzed with the monitoring service. To publish a monitoring event please use the Context.get().monitorEvent(...) methods. These special events are also written into a separate log file, so that they are distinguishable from the standard logs.

Choose the monitoring over the local logging whenever you can, so that you enable rich analytics for your application.

You can use the following line as a template:

Context.get().monitorEvent(MonitoringEvent.SERVICE_CUSTOM_MESSAGE_X, "Provide here some information that can be evaluated");

For different events just replace X with a different number.

For other variants of the method, please refer to the Java docs.

If you explicitly want to disable monitoring for your service, use the @DoNotMonitor annotation on your service's main class.

XES Event Logging

The Monitoring Service also allows you to log events in the XES format. This is useful to analyze your service from a process mining perspective. For this, the las2peer logger provides a method to log events in the XES format. The method is called monitorXESEvent and can be used as follows:

Context.get().monitorXESEvent(event, message, caseId, activityName, resourceId, resourceType, lifecyclePhase, timeOfEvent)

The parameters are as follows:

• event: The event to be logged. This can be any of the predefined events in the MonitoringEvent enum.
• message: A message that describes the event.
• caseId: The case ID of the event. This is used to group events together that belong to the same case. For example, if you want to log a sequence of events that belong to the same process instance, you should use the same case ID for all of them.
• activityName: The name of the activity that the event is related to. This is used to identify the activity in the process model.
• resourceId: The ID of the resource that the event is related to. This is used to identify the resource in the process model. The resource ID should be unique for each resource.
• resourceType: The type of the resource that the event is related to. This is used to identify the resource in the process model.
• lifecyclePhase: The lifecycle phase of the resource that the event is related to. This is used to identify the resource in the process model.
• timeOfEvent: The time when the event occurred. This is used to order the events in the process model.

The mobsos event log generator will then use this information to generate an XES event log that can be analyzed with process mining tools.

Success models

The logged data can be evaluated by the Monitoring Service by an xml file containing the specified success_model. These models contain of six different categories (System Quality, Information Quality, Use, User Satisfaction, Individual Impact and Community Impact).

Template of a success_model;

<SuccessModel name="Name of your success model" service="your.service.name@version">
 <dimension name="System Quality">
  <factor name="No Factors or Measures yet">
  </factor>
 </dimension>

 <dimension name="Information Quality">
  <factor name="No Factors or Measures yet">
  </factor>
 </dimension>

 <dimension name="Use">
  <factor name="No Factors or Measures yet">
  </factor>
 </dimension>

 <dimension name="User Satisfaction">
  <factor name="No Factors or Measures yet">
  </factor>
 </dimension>

 <dimension name="Individual Impact">
  <factor name="No Factors or Measures yet">
  </factor>
 </dimension>

 <dimension name="Community Impact">
  <factor name="No Factors or Measures yet">
  </factor>
 </dimension>
</SuccessModel>

A factor can be specified by a measure.

<factor name="Factorname">
    <measure name="Your measurement"/>
</factor>

The Monitoring Service needs a SQL statement for that measurement.

<measure name="Your measurement">
 <query name="countOfMessageX">
  SELECT COUNT(*) as number FROM monitoringTable.MESSAGE
  WHERE EVENT =  'SERVICE_CUSTOM_MESSAGE_X' AND SOURCE_AGENT = '$SERVICE$'
 </query>
 <visualization type="KPI">
  <operand name="countOfMessageX" index="0"/>
 </visualization>
</measure>

You can use multiple queries. For the visualization just increase the index of the operand and match the name of the operand with the associated query. The queries are stored in the measurement catalog.