JBoss.orgCommunity Documentation

Chapter 2. Reporting Activity

2.1. Activity Model
2.1.1. Activity Unit
2.1.2. Origin
2.1.3. Context
2.1.4. Activity Type
2.2. Activity Collector
2.2.1. Finding the Activity Collector
2.2.2. Pre-Processing Activity Information
2.2.3. Validating the Activity Event
2.2.4. Managing the Activity Scope
2.2.5. Reporting an Activity Type
2.2.6. Configuring an Activity Unit Logger
2.2.7. Configuring a Collector Context
2.2.8. Simplified Activity Reporter for use by application components
2.3. Activity Server
2.3.1. Recording Activity Units
2.3.2. Retrieve an Activity Unit
2.3.3. Retrieve a list of Activity Events

The section provides an overview of the Activity Model. This model defines the set of events (or situations) that can be reported to identify what is happening during the execution of a business transaction.

All activity events are derived from an Activity Type superclass. This class has the following information:

  • activity unit id
  • activity unit index
  • timestamp
  • principal
  • a set of contexts
  • a set of properties

The only piece of information that needs to be provided by the reporting component is the timestamp, and optionally some activity type specific contexts. The other information will be initialized by the infrastructure prior to persisting the Activity Unit, as a way to enable the specific Activity Type instance to be located. This may be required during the analysis of Activity Units.

The BPM (Business Process Management) specific activity events are used to record the lifecycle and state transitions that occur when a business process (associated with a description language such as BPMN2 or WS-BPEL) is executed within a runtime engine, in support of a business transaction.

These business processes tend to be "long running", in that they handle multiple requests and responses over a period of time, all being correlated to the same process instance. This means that activities generated as a result of this execution must also be correlated to \(i) the specific XA transaction in which they are performed, (ii) the process instance that holds their state information in the BPM engine, and (iii) the conversation associated with the particular business transaction.

This does not mean that all Activity Units the contain activity information from the BPM engine need to have all three types of correlation information. For example, the initial Activity Unit for a business process instance may identify (i) and (ii), which will establish a unique process instance id. A subsequent Activity Unit may then define the same process id for (ii), as well as a conversation id (iii) that can then be used to tie any Activity Unit relates with the process instance id to that conversation - i.e. all Activity Units with the same process instance id become directly or indirectly correlated to the conversation id that may only be declared in some of the Activity Units.

Activity TypeDescription

ProcessStarted

This activity type will be recorded when a process instance is initially started.

Attributes include: process type, instance id and version

ProcessCompleted

This activity type will be recorded when a process instance completes.

Attributes include: process type, instance id and status (either success or fail)

ProcessVariableSet

This activity type will be recorded when a process variable’s value is set or modified.

Attributes include: process type, instance id and variable name/type/value

The Activity Collector is an embedded component that can be used to accumulate activity information from the infrastructure used in the execution of a business transaction. The activity information is then reported to the Activity Server (described in the following section) implicitly, using an appropriate Activity Logger implementation. The default Activity Logger implementation operates efficiently by providing a batching capability to send activity information to the server based either on a regular time interval, or a maximum number of activity units, whichever occurs first.

An Activity Scope is a way of grouping a range of different activity types, that will be reported to the activity server, into a single logical unit. It should generally represent the same scope as a XA transaction, to emcompass all of the work that was achieved within that transaction - and equally be discarded if the transaction is rolled back.

When the first activity is reported within the scope of a XA transaction, then the scope will automatically be started. When that transaction subsequently commits, the Activity Unit (i.e. the collection of activities accumulated during that scope) will be reported to the Activity Server.

However if activities are performed outside the scope of a XA transaction, then the component reporting the activity information can either explicitly start a scope, or just report the activity information.

If no scope exists, and an activity type is reported, then it will simply be reported to the activity server as a single event. The disadvantage of this approach is that it is less efficient, both in terms of reporting due to the duplication of certain header information, and for subsequent analysis. Having multiple activity events defined in a single unit, related to the transaction, provides added value to inter-relating the different events - providing some implied correlation that would not exist if the events were independently reported to the Activity Server.

As described above, activity information is reported to the server as an Activity Unit, containing one or more actual activity events. The activity event is generically known as an Activity Type.

The Activity Collector mechanism removes the need for each component to report general information associated with the Activity Unit, and instead is only responsible for reporting the specific details associated with the situation that has occurred.

The set of different Activity Types that may be reported is outside the scope of this section of the documentation, and so for the purpose of illustration we will only be using a subset of the SOA related activity events. For more informaton on the available event types, please refer to the javadocs.

To report an event, simply create the specific Activity Type and invoke the record method:

org.overlord.rtgov.activity.model.RequestSent sentreq=new org.overlord.rtgov.activity.model.soa.RequestSent();

sentreq.setServiceType(serviceType);
sentreq.setOperation(opName);
sentreq.setContent(content);
sentreq.setMessageType(mesgType);
sentreq.setMessageId(messageId);

activityCollector.record(sentreq);

For certain types of event, it may also be appropriate to invoke an information processor(s) to extract relevant context and property information, that can then be associated with the activity event. This is achieved using the following:

Object modifiedContent=_activityCollector.processInformation(null,
          mesgType, content, headers, sentreq);

sentreq.setContent(modifiedContent);

The activity collector can be used to process relevant information, supplying the activity type to enable context and property information to be defined. The result of processing the information may be a modified version of the content, suitably obsfucated to hide any potentially sensitive information from being distributed by the governance infrastructure.

The first parameter to the processInformation() method is an optional information processor name - which can be used to more efficiently locate the relevant processor if the name is known.

The Activity Unit Logger is the component responsible for logging the activity unit that is generated when the endScope method is invoked on the collector (either explicitly or implicitly by the XA resource manager).

This interface has three methods:

  • init - this method initializes the activity unit logger implementation
  • log - supplied the Activity Unit to be logged
  • close - this method closes the activity unit logger implementation

Although the general Activity Collector mechanism can be used, as described in the previous sections, an injectable ActivityRecorder component is provided to enable applications to perform simple activity reporting tasks. Where injection is not possible, then a default implementation of the interface can be instantiated.

For example, the sample SwitchYard order management application uses this approach:

@Service(InventoryService.class)
public class InventoryServiceBean implements InventoryService {

    private final Map<String, Item> _inventory = new HashMap<String, Item>();

    private org.overlord.rtgov.client.ActivityReporter _reporter=
		new org.overlord.rtgov.client.DefaultActivityReporter();

    public InventoryServiceBean() {
        ....
    }

    @Override
    public Item lookupItem(String itemId) throws ItemNotFoundException {
        Item item = _inventory.get(itemId);

        if (item == null) {

            if (_reporter != null) {
                _reporter.logError("No item found for id '"+itemId+"'");
            }

            throw new ItemNotFoundException("We don't got any " + itemId);
        }

        ....

        return item;
    }
}

The ActivityReporter enables the application to perform the following tasks:

MethodDescription

logInfo(String mesg)

Log some information

logWarning(String meg)

Log a warning

logError(String mesg)

Log an error

report(String type, Map<String,String> props)

Record a custom activity with a particular type and associated properties

report(ActivityType activity)

Record an activity

However this API cannot be used to control the scope of an ActivityUnit. It is expected that this would be handled by other parts of the infrastructure, so this API is purely intended to simplify the approach used for reporting additional incidental activities from within an application.

The maven dependency required to access the ActivityReporter is:

		<dependency>
			<groupId>org.overlord.rtgov.integration</groupId>
			<artifactId>rtgov-client</artifactId>
			<version>${rtgov.version}</version>
		</dependency>

The Activity Server is responsible for:

  • Recording Activity Units describing the activities that occur during the execution of business transactions in a distributed environment.
  • Query suport to retrieve previously recorded Activity Units

The Activity Server can be used to record a list of Activity Units generated from activity that occurs durig the execution of a business transaction. The Activity Units represent the logical grouping of individual situations that occur within a transaction (e.g. XA) boundary.

This section will show the different ways this information can be recorded, using a variety of bindings.

Tip

Where possible, the Activity Collector mechanism described in the previous section should be used to aggregate and record the activity information, as this is more efficient that each system individually reporting events to the server.

The Activity Server can be used to retrieve a specific Activity Unit from the Activity Server. The Activity Unit represents a grouping of Activity Events that occurred within the same business transaction scope. This section will show the different ways this information can be queried, using a variety of bindings.

The Activity Server can be used to query a list of Activity Type (events) from the Activity Server. This section will show the different ways this information can be queried, using a variety of bindings.