Friday, February 28, 2014

Run Time Governance Quickstarts in Fuse Service Works



I - Overview
II - Setup
III -  Synchronous Enforcement Quickstart
IV - Asynchronous Enforcement Quickstart
V - SLA Monitor Quickstart
VI - SLA Report Quickstart

Overview 

First a quick overview and then a run through of the Run Time Governance Quickstarts.  This was compiled from http://docs.jboss.org/overlord/rtgov/quickstart/1.0.0.Final/html_single/index.html and https://access.redhat.com/site/documentation/en-US/Red_Hat_JBoss_Fuse_Service_Works/6/html-single/Development_Guide_Volume_3_Governance/index.html.

In SwitchYard, the applications are exposed as shared business processes or services. In a shared environment, the most common challenges revolve around access control, access rights, security issues, and service authorizations. SwitchYard uses Run-Time Governance to facilitate complete control over the shared services by following a policy based approach. SwitchYard classifies Run-Time Governance into two aspects:
  • Policy definition and enforcement
  • Collection and exposure of run-time metrics for services and service references
The architecture is separated into four distinct areas, with components that bridge between these areas:
  • Activity Collector - this component is optional, and can be embedded within an executing environment to manage the collection of information
  • Activity Server - this component provides a store and query API for activity information. If not using the Activity Collector, then activity information can be reported directly to the server via a suitable binding (e.g. REST).
  • Event Processor Network - this component can be used to analyse the activity information. Each network can be configured with a set of event processing nodes, to filter, transform and analyse the events, to produce relevant rules.
  • Active Collection - this component is responsible for maintaining an active representation of information being collected. UI components can then access this information via REST services to present the information to users (e.g. via gadgets)
Setup

This blog assumes you have Fuse Service Works installed from jboss.org/products/fsw.html with RTGov and the quickstarts installed.

Open jboss-eap-6.1/standalone/configuration/overlord-rtgov.properties and modify collectionEnabled to be true before starting Fuse Service Works.

Start the server

./standalone.sh -c standalone-full.xml

Next we want to test and deploy the ordermgmt and ip quickstarst. First change to the jboss-eap-6.1/quickstarts/overlord/rtgov/ordermgmt folder. Go under the ip (Information Processor) folder. This quickstart provides an example configuration for information processors related to the messages sent and received by the Order Management application. These information processors are responsible for extracting information that may be required in subsequent event processing.   The information processor is defined in src/main/resources/ip.json  Deploy the Information Processing Definitions.

mvn jboss-as:deploy

Next let's change to the app folder.   This quickstart provides an example SwitchYard application, based on the Orders demo from the SwitchYard
project.  The service accepts either an order or a payment.  Orders are checked with the inventory service and if available, the order is accepted and finally sent to the logistics service to be delivered to the customer.  The RTGov hook is in the org.overlord.rtgov.quickstarts.demos.orders.interceptors.ExchangeValidator.  Now let's deploy the Switchyard application.


mvn jboss-as:deploy

To test the service, there are a set of example request SOAP messages defined in the test/main/resources/xml folder. These can be sent to the service using a SOAP client (e.g. SOAP UI), or using the following command:

    mvn exec:java -Dreq=<name> [ -Dcount=<number> ]

The 'req' property specifies the name of the request SOAP XML file. Available values are:
  • order1 - Valid order for BUTTER, from customer Fre
  • order2 - Invalid order for LAPTOP, from customer Fred, due to item not being available
  • order3 - Valid order for JAM, from customer Fred, which results in a delay causing SLA violations
  • order4 - Valid order for BUTTER, from customer Joe
  • fredpay - Fred makes a payment
The 'count' property represents the number of requests that will be sent - the default value is 1.

Let's confirm the application is running.

mvn exec:java -Dreq=order1

You should see the accepted order status.

Reply 1:
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"><SOAP-ENV:Header xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"/><soap:Body><orders:submitOrderResponse xmlns:orders="urn:switchyard-quickstart-demo:orders:1.0"><orderAck><orderId>1</orderId><accepted>true</accepted><status>Order Accepted</status><customer>Fred</customer><total>125.0</total></orderAck></orders:submitOrderResponse></soap:Body></soap:Envelope>


Policy Enforcement

The examples located in the samples/policy folder, demonstrates two approaches that can be used to provide "policy enforcement". This example makes uses of the example in Switchyard
application, located in the samples/ordermgmt folder.

Synchronous Enforcement

The runtime governance infrastructure analyses the activity events generated by an executing business transaction using one or more Activity Validators. By default, Activity Validators are not invoked from within the SwitchYard environment. The specific SwitchYard applications need to be configured to include an auditor that will invoke the validation. In the Order Management quickstart, this is achieved using the class org.overlord.rtgov.quickstarts.demos.orders.auditors.ExchangeValidator. This class is derived from an abstract base class that provides most of the required functionality for converting an Exchange message into an activity event.

Change the directory to jboss-eap-6.1/quickstarts/overlord/rtgov/policy/sync and deploy the quickstart.

mvn jboss-as:deploy

To demonstrate the synchronous policy, we will send the following message twice in less than 2 seconds.  Run the test client available with the Switchyard application, by running the following command from the ${rtgov}/samples/ordermgmt/app folder:

mvn exec:java -Dreq=order1 -Dcount=2

If the two requests are received within two seconds of each other, this will result in the following response.

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <soap:Fault>
         <faultcode>soap:Server</faultcode>
         <faultstring>org.switchyard.exception.SwitchYardException: Customer 'Fred' cannot perform more than one request every 2 seconds</faultstring>
      </soap:Fault>
   </soap:Body>
</soap:Envelope>

This quickstart example demonstrates how a policy enforcement mechanism can be provided using the Activity Validator mechanism, to immediately evaluate the business policy and (if appropriate) block the business transaction.

Asynchronous policy

This approach shows how a business policy can be implemented in an asynchronous (or out-of-band) manner, where the decision is taken after the fact, and can therefore only be used to influence future business transactions. The benefit of this approach is that the decision making process does not have to occur immediately and therefore avoids potentially impacting the performance of the business transaction. The disadvantage is that it does not permit any decision that is made to be enforced immediately.
This example will show how:
  • activity event analysis, using the Event Processor Network mechanism, can be used to implement business policies
  • results from the business policies can be cached for reference by other applications
  • platform specific interceptors can reference the results to impact the behavior of the business transaction (e.g. prevent suspended customers purchasing further items)
An mvel based policy to assess credit, implemented in an asynchronous (or out-of-band) manner. Action is taken after execution and then alters future transactions.

Change the directory to jboss-eap-6.1/quickstarts/overlord/rtgov/policy/async and deploy the quickstart.

mvn jboss-as:deploy

To demonstrate the asynchronous policy enforcement, we will send the following message to the example Switchyard application.  Run the test client available with the Switchyard application, by running the following command from the ${rtgov}/samples/ordermgmt/app folder.

mvn exec:java -Dreq=order1

This will result in the following response, indicating that the purchase was successful, as well as identifying the total cost of the purchase (i.e. 125).

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <orders:submitOrderResponse xmlns:orders="urn:switchyard-quickstart-demo:orders:1.0">
         <orderAck>
            <orderId>1</orderId>
            <accepted>true</accepted>
            <status>Order Accepted</status>
            <customer>Fred</customer>
            <total>125.0</total>
         </orderAck>
      </orders:submitOrderResponse>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

You may recall from the overview above that if the customer’s debt exceeds the threshold of 150 then the customer would be suspended. Therefore if the same request is issued again, resulting in another total of 125, then the overall exposure regarding this customer is now 250.

If we then attempt to issue the same request a third time, this time we will receive a SOAP fault from the server. This is due to the fact that the PolicyEnforcer auditor has intercepted the request, and detected that the customer is now suspended.

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
      <SOAP-ENV:Fault>
         <faultcode>SOAP-ENV:Server</faultcode>
         <faultstring>Customer 'Fred' has been suspended</faultstring>
      </SOAP-ENV:Fault>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

If we now send a "makePayment" request as follows to the same URL:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:urn="urn:switchyard-quickstart-demo:orders:1.0">
   <soapenv:Header/>
   <soapenv:Body>
      <urn:makePayment>
         <payment>
            <customer>Fred</customer>
            <amount>200</amount>
         </payment>
      </urn:makePayment>
   </soapenv:Body>
</soapenv:Envelope>

This can be sent using a suitable SOAP client (e.g. SOAP-UI) or the test client in the order management app:

mvn exec:java -Dreq=fredpay

This will result in the customer being unsuspended, as it removes 200 from their current exposure (leaving 50). To confirm this, try sending the "submitOrder" request again.

This quickstart example demonstrates how a policy enforcement mechanism can be provided using a combination of the Runtime Governance infrastructure and platform specific interceptors.   This particular example uses an asynchronous approach to evaluate the business policies, only enforcing the policy based on a summary result from the decision making process. The benefit of this approach is that it can be more efficient, and reduce the performance impact on the business transaction being policed. The disadvantage is that decisions are made after the fact, so leaves a tiny window of opportunity for invalid transactions to be performed.

SLA Monitoring

This example, located in the samples/sla/monitor folder, demonstrates an approach to provide "Service Level Agreement" monitoring. This example makes uses of the example Switchyard application located in the samples/ordermgmt folder.

This example will show how:
  • activity event analysis, using the Event Processor Network mechanism, can be used to implement Service Level Agreements
    • uses the Complex Event Processing (CEP) based event processor (using Drools Fusion)
  • impending or actual SLA violations can be reported for the attention of end users, via
    • JMX notifications
    • REST service
  • to build a custom application to access the analysis results
This example shows a simple Service Level Agreement that checks whether a service response time exceeds expected levels. The CEP rule detects whether a situation of interest has occurred, and if so, creates a org.overlord.rtgov.analytics.situation.Situation object and initializes it with the appropriate description/severity information, before forwarding it back into the EPN. This results in the "Situation" object being published as a notification on the "Situations" subject.
 
Run the same command from the ${rtgov}/samples/sla/epn and ${rtgov}/samples/sla/monitor folders.

mvn jboss-as:deploy

To demonstrate a Service Level Agreement violation, we will send the following message to the example Switchyard application.

Run the test client available with the Switchyard application, by running the following command from the ${rtgov}/samples/ordermgmt/app folder:

mvn exec:java -Dreq=order3

The itemId of "JAM" causes a delay to be introduced in the service, resulting in a SLA violation being detected. This violation can be viewed using two approaches: REST Service and JMX Console.

REST Service

Using a suitable REST client such as a RESTClient in Firefox , send the following POST to: http://localhost:8080/overlord-rtgov/acm/query (using content-type of "application/json", username is admin and password).

{
    "collection" : "Situations"
}

The response will be a JSON response.

JMX Console

The Situations active collection source also generates JMX notifications that can be subscribed to using a suitable JMX management application. For example, using JConsole we can view the SLA violation.


This quickstart demonstrates how Service Level Agreements can be policed using rules defined in an Event Processor Network, and reporting to end users using the pre-configured "Situations" active collection.

The rule used in this example is simple, detecting whether the response time associated with an operation on a service exceeds a particular level. However more complex temporal rules could be defined to identify the latency between any two points in a business transaction flow.

SLA Reporting

This example, located in the samples/sla/report folder, demonstrates how to provide pluggable reports that can access information in the activity store. This particular example uses the activity information to compile a Service Level Agreement report, highlighting violations above a specified response time.

This example will show how:
  • to configure a pluggable report
  • to generate the report via a REST API
This example provides a simple Service Level Agreement report, based on identifying service invocations that exceed a specified maximum response time over an optionally specified averaged duration. If the averaged duration is not specified, then each service invocation will be checked to determine if it exceeded the maximum response time - and if so, get added to the report. If the averaged duration is specified, then when an invocation is detected (that exceeds the max response time), then all other suitable invocations within the specified duration are averaged to determine if the response time overall still exceeds the specified maximum. This is to ensure that periodic spikes are not unnecessarily reported.

It is also possible to optionally specify a business calendar, which can be used to determine the business period in which activities are of interest. If SLA violations occur outside the specified business calendar, then they are not relevant.

To demonstrate a Service Level Agreement report, we will need to create some relevant activities that can be reported upon. Send multiple instances of the following messages to the example Switchyard application

Run the test client available with the Switchyard application, by running the following commands from the ${rtgov}/samples/ordermgmt/app folder:


mvn exec:java -Dreq=order1
mvn exec:java -Dreq=order3

To generate a report, we will send a GET request to the following URL using the Basic Authentication username admin and password:

http://localhost:8080/overlord-rtgov/report/generate?report=SLAReport
  &startDay=1&startMonth=1&startYear=2013&endDay=31&endMonth=12
  &endYear=2013&maxResponseTime=400&averagedDuration=450

This will return a report (with name SLAReport) containing violations that occur within the year 2013. If you wish to experiment with the default business calendar, then append "&calendar=Default" to the end of the URL. This will also identify what percentage of the business working period has been impacted by the SLA violations.

This quickstart demonstrates how report definitions can be deployed to the Runtime Governance infrastructure and invoked to generate a report instance via a REST service.