Monitoring and Logging

Applications deployed on Fabric3 can take advantage of its built-in injection-based monitoring framework for logging and recording application events. The monitoring framework offers a number of benefits:

• Strongly-typed monitoring interfaces and events
• High performance logging (millions of events per second) with no garbage creation for latency-sensitive appications
• Dynamic event level adjustment

Using Monitoring

To use the monitoring framework in application code entails two things, creating a monitor interface and injecting the monitor in a component.

Define a Monitor Interface.

The monitor interface is used for sending monitoring events. The interface defines operations for publishing events, monitoring levels and optional event message templates:

import org.fabric3.api.annotation.monitor.Severe;
import org.fabric3.api.annotation.monitor.Debug;

public inteface ComponentMonitor

   @Severe
   void error(String message, Throwable t);

   @Debug ("Received request {0}")
   void receivedRequest(String id);

}

The above interface defines an error event and a debug event. The debug event also specifies a formatted message that will be logged if the event is received. The following monitoring levels are supported:

• Severe - Critical errors that affect continue runtime operation
• Warning - Error conditions that do not affect continued runtime operation or a potential runtime configuration issue
• Info - Informational event
• Debug - An event useful for diagnosing a problem
• Trace - A low level event useful for diagnosing a problem

By default, Info and above are enabled at runtime.

Injecting the Monitor

A monitor is injected in a component using the org.fabric3.api.annotation.monitor.Monitor annotation:

import org.fabric3.api.annotation.monitor.Monitor;

public void TheComponent {

   @Monitor
   protected ComponentMonitor monitor;

   public void call(Message message) {
      monitor.receivedRequest(message.getId);
      try{
         validate(message));
      } catch (ValidationException e) {
         // bad message
         monitor.error("Invalid message", e)
      }

      // ...

   }

When an @Monitor annotation is encountered, the Fabric3 runtime will generate a monitor proxy and inject it based on the monitor interface. Depending on the current monitor level, events may be recorded or ignored. In the above example, if the monitor level is set to severe, the receivedRequest() event will be dropped.

Configuration

Monitor events are sent to a destination.  A destination has one or more appenders that act as sinks for monitor events. It is possible to create a custom appender (detailed below) or use one of the provided appenders such as the file or console appenders. An application (or service) can send events to a custom destination or use the default runtime destination. Sending events to a custom destinations allows traffic for a particular application, subsystem or service to be segmented from other events.  

Configuring the Runtime Destination

The default runtime destination is where Fabric3 runtime events (and application events if not specified) are sent. The default destination can be configured in systemConfig.xml , for example, to record events to a log file instead of outputting to the console. The monitor element is used to add appenders 

•  <monitor>
•         <appenders>
•             <appender.file file="fabric3.log"/>
•             <appender.console/>
•         </appenders>
•     </monitor>

Configuring Custom Destinations

Ring Buffer Destinations

Custom Appenders

Configuration Reference

Performance Considerations

By default, Fabric3 uses JDK proxies to implement monitor interfaces. For most code paths in an application, this should not introduce significant performance impact as there are optimizations to avoid object creation when events are discarded. However, for performance intensive code paths, JDK proxies may introduce too much overhead.