Message Tracing

This sample explains about the message tracing and visualization with BAM. That is a request can be sent to the end point by passing through some intermediate stages, and by using BAM we can trace each messages and visualize the message body in each intermediate stage.

In this sample we'll consider a use case, that request for a web services to 'PlaceOrder' travels through some sequences in ESB and then it reaches the end point web service.

Message Tracing sample sequence flow

Assume a situation where the Order placing web services fronted by a proxy service, and the proxy service consists of the above sequences to mediate the message. As shown in the above diagram, the message first arrives to the 'AuthenticateSequence' and then it'll authenticate the credit card credentials and the account balance for the purchase. In the case of failure of authentication the message will be directed to AuthencateErrorHandlerSequence. In the success case the message will be dispatched to the 'PlaceOrderSequence'. Further here the main order processing will occur and in the case of failure of processing the order, the message will be dispatched to the 'PlaceOrderErrorHandlerSequence'.

In the each of the sequences for the IN and OUT the event will be published to the BAM with bam_activity_id and the current_sequence_name. Therefore the message can be identified by it's unique bam_activity_id and can trace how the message was dispatched from end-to-end. And in the case of failure of message, the message failure can be traced with visualizing the message path.

We'll consider the above use case in this sample, and see how we can trace the message from end-to-end. Each of the above steps will be described in detail in the following steps.

Step 1 - Start BAM Server

  1. Download the WSO2-BAM Server
  2. Unzip the WSO2-BAM.zip in the location where ever you prefer
  3. Go to WSO2-BAM-HOME/bin folder in comman prompt. And type
    • wso2server.sh (For ubuntu, linux, mac OS)
    • wso2server.bat (For Windows)


Step 2 - Sending events to BAM Server.

Pre-requisites: Apache-ant

Make sure you machine has apache-ant, if not please install the apache-ant.(http://ant.apache.org/)

  1. Go to location from command prompt WSO2-BAM-HOME/samples/end-to-end-messageTracing
  2. In this folder you can see the build.xml. Type 'ant' command from the command propmt. This will simulate success and failure message requests for ESB and will pump the events to BAM

Step 3 - Create Index

We need to create the Index for the BASE column family as the events received by BAM is directly stored here. This index is used to filter out the events which has the bam_activity_id and will group them together.

At this moment we need to create the ClusterStreamSelector. Follow the below given steps to create the index.

  1. Login to the BAM management console. The link for the management console will be there in the server startup log. You can click on it and log in to the management console. Or you can go to https://localhost:9443/ in your web browser, this will take you to the management console.
  2. Go to Configure → Connection Parameters. There you can provide the connection parameter for the cassendra source. Default username, password is admin, admin. Click on Save button after filling out the connection paramters.
  3. Go to Configure → BAM Database


  4. Add index main page

  5. Click on the Add Index.

  6. Create Index named ActivityIndex, as shown below. And click Save.


  7. Add Index


Step 4 - Create Analyzer

In the analyzer you need to write the analytics such that it analyzes the gathered data by the BAM according to you requirement. In this sample we are interested in viewing the message trace from end-to-end, therefore we'll be writing such that the events with same bam_activity_id will be group up (Which corresponds to the one request), and sorted by the time stamp of the event.

The analyzer sequence for this situation,

<analyzerSequence name="MessageTracing">                                                                  
   <trigger cron="1 * * * * ? *"/>                                                                  
   <analyzers>                                                                                                                                                                                                        
      <get name="BASE" batchSize="100">                                                                                                                                                         
         <where index="ActivityIndex">                                                                         
            <range column="bam_activity_id" start="" end=""/>                                                        
         </where>                                                                                                                                                        
      </get>                                                 
      <groupBy>                                                                         
         <field name="bam_activity_id"/>                                                
      </groupBy>                                                                           
      <orderBy field="timestamp"/>                                                                                                                       
   </analyzers> 
</analyzerSequence>  

The above given analyzer sequence is given in the WSO2BAM/Samples/end-to-end-messageTracing/MessageTracing.xml. Follow the below given steps to ad dthe analyzer sequence to the BAM server.

  1. Go to WSO2BAM/samples/end-to-end-messageTracing folder
  2. Open the MessageTracing.xml and copy the content
  3. Go to Configure → Analyzer Framework


  4. Add analyzer main page

  5. Click on 'Add sequence' and go to the source view of the analyzer sequence.


  6. Paste the content from the MessageTracing.xml in the step-2, and click on 'Save All' button.


  7. Add analyzer

Now you can see two index from the index table as below.



All Index table



Step 5 - Create Gadget

In this section we cna see how to design your own gadgets according to your requirement. In this section we created table to visulaize the message details of the events.

The below given steps will explain how to create the gadgets and visualize the data collected.

  1. Go to Configure → Gadget IDE
  2. In order to obtain the unique data of bam_activity_id, there is a web service in BAM. To communicate with web service, click on the 'Web Service (WSDL)' in the Gadget IDE.That is since a message with corresponds to a unique bam_activity_id, will be having more than one events as it pass through many sequences. Therefore to obtain the unique bam_activity_id s' from pool of events we need to use the webservice

  3. Web sevice gadget

  4. You can see the WSDL of the web service mentioned above, in https://localhost:9443/services/IndexAdminService?wsdl2. Insert this WSDL file url in the gadget, as below. And click on 'load' button.


  5. Web service gadget after load

  6. Select 'getIndexValues' for the field 'Operation' in the WSDL gadget.


  7. Web service gadget after selecting getIndexvalues operation

  8. Click on the Text and connect as below. Note the two Text gadgets have been used. One text field here will mention the indexName, and other one will mention the indexedColum which as two parameters which is required to to the 'getIndexValues' operation. Therefore we should pass the respective Index name and indexed column name we created for the ActivityIndex.
    IndexName --> AcivityIndex
    IndexedColumn –-> bam_activity_id


  9. Web service gadget with text gadget



  10. Now click on 'Combo box'. It'll immediately take to the design view, there you can resize and locate the combo box where ever you like. Then switch back to the 'DataFlow' view. Connect the 'return' node from the WSDL gadget to the 'text' node of the combo box as shown below.


  11. Web service gadget with combo box

  12. This states the return value from the web service method is used to fill the combo box. Now go to the design view, there you can see the unique bam_activity_id (which is returned from the web service)


  13. Combo box in design view

  14. Click on the Cassendra sources. And fill it as the following and click on load button
    • Tablename: BASE (Where the events are dumped in the BAM server)
    • TableIndexName: ActivityIndex
    • Index: bam_activity_id


    Cassendra source gadget



  15. Click on the lexical string and and connect as below shown.
    • Combo box-text → Cassendra source-from0
    • Combo box-text → lexicalString-text
    • lexicalString-text → cassendra source-to
  16. Click on the table. It'll take to the design view, locate and resize the gadget as you prefer.


  17. Switch to the Dataflow view. Connect
    • Cassendra Source-rows → rows-Table.


    Final data flow



  18. Switch to the design view and see the table. Here you can select the bam_activity_id from combo box which implicitly selecting each request and see the respective events published in the sequences.
    • One message shows the success path. The belowfigure shows the such success path and the table data.In the below view you can notice that the message has passed thorough all the IN and OUT sequences and therefore it's a succesfull message.


    • All Success sequence

    • In the below message, you can notice the authentication has failed and therefore didn't pass to the place order sequence. You can see the message body to view the reason to the failure and it says 'Not enough creadit avaliable in the account'


    • Authentication failure

    • Similarly you can see the message fails in the placeOrder sequence, the reason cab be idetified via the message body. And can be notices the reasons is 'No enough product in stock'


    • Place Order failure

  19. Now you can see the created gadget from the main dash board.

Step 6 - Publish the gadget to dashboard

  1. Go to the settings in gadget ide side pane and click on the publish


  2. Publish gadget

  3. Type a name of the gadget and click on publish. A URL will be popped out. Copy the URL.
    Eg: /registry/resource/_system/config/repository/dashboards/gadgets/ClusterSummary.xml

    Publish gadget URL
  4. Go to BAM server home page, and click on the BAM dashboard.
  5. Click on the Add Gadget, and paste the URL copied which publishing the gadget.
  6. Add click on the add gadget.

Now we have come to the end of the sample and now you know the way of generating the custom gadgets from BAM and tracing the messages.