Monitor > Monitor application flow

Request metric extension

Certain applications might require additional instrumentation points within the request metrics flow. For example, we might want to understand the response time to a unique back-end system as seen in the following call graph:

Request metrics uses a "token" or "correlator" when tracing the flow of each request through the system. To create the call graph above with this instrumentation, we must plug into that flow of the request and issue the appropriate Application Response Measurement (ARM) API for an ARM agent to collect the data and for the ARM vendor to create the call graph.

Request metrics exposes the Correlation Service API for you to plug into the flow of the request. The following example is one of the typical flows that might be followed by an instrumented application to plug into the request metrics flow:

  1. Create a new ArmTransaction object, which runs various instrumentation calls such as start or stop. The Correlation Service Arm wrapper (PmiRmArmTx) encapsulates this object before being inserted into the request metrics flow.

  2. Populate the ArmTransaction object with an appropriate ArmCorrelator object. This object encapsulates the actual ARM correlator bytes.

  3. Run the start method on the ArmTransaction object, marking the beginning of the instrumented method.

  4. Instantiate a PmiRmArmTx object using the static method on the PmiRmArmTxFactory class, and populate the PmiRmArmTx object with the ArmTransaction preceding object.

  5. Pass the PmiRmArmTx preceding object to the Correlation Service by pushing it onto the Correlation Service stack using exposed methods on the PmiRmArmStack class.

  6. Perform the tasks to be done by the method being instrumented. The Correlation Service takes care of flowing the ArmTransaction object as necessary, which eventually results in the call graph view of the transaction times.

  7. At the end of the instrumented method, access the PmiRmArmTx object from the Correlation Service using exposed methods on the PmiRmArmStack class, access the ArmTransaction object and perform a stop to indicate the end of the transaction.

The arm40 binaries should be installed in accordance with the installation instructions supplied by the implementation provider. Once this is done, restart the server. This causes trace records to be generated in the SystemOut.log file indicating the instantiation of the appropriate ARM implementation. The following example illustrates one of the typical workflows of using the ARM API in conjunction with the correlation service as part of a servlet instrumentation: 

public void doGet(HttpServletRequest request, HttpServletResponse response)
  throws ServletException, IOException {

PmiRmArmTx artrax = PmiRmArmTxFactory.createPmiRmArmTx();
// The factory detects the currently active ARM implementation (specified by user through 
// admin console) and instantiates an appropriate ARM wrapper object 

ArmTransaction at = newArmTx();
if (null == at)
    out.println("Got a null ArmTransaction");
ArmCorrelator arc = newArmCorr();
at.start(arc);
try {
 artrax.setArmTransaction(at);
 PmiRmArmStack.pushTransaction(artrax);} catch (Exception e) {
 System.out.println("Caught 1 exception" + e);}

PmiRmArmTx atxwrp = PmiRmArmStack.peekTransaction();

if (atxwrp == null)
 out.println("Armtransaction is null");

//getArmType
try {
 out.println("ARMTYPE is"+ PmiRmArmTx.getARMType());} catch (Exception e) {
 out.println(e);}
//getting correlator bytes
try {
 if (null == atxwrp.getCorrelatorBytes())
  out.println("Got a null Correlator");} catch (Exception e) {
 out.println(e);}

//blocked/unblocked
long blkid = 0;
try {
 out.println(blkid = atxwrp.blocked());} catch (Exception e) {
 out.println(e);}

try {
 out.println(atxwrp.unblocked(blkid));} catch (Exception e) {
 out.println(e);}
try {
 atxwrp = PmiRmArmStack.popTransaction();
 ArmTransaction art = (ArmTransaction) atxwrp.getArmTransaction();
 art.stop(ArmConstants.STATUS_GOOD);} catch (Exception e) {
 out.println(e);}
}



private ArmTransaction newArmTx() {

 ArmTransactionFactory txFactory = null;
try {
 String sWasName = "WebSphere";
 String appName = "t23xpimage/t23xpimage/server1";
 String sCellName = appName.substring(0, appName.indexOf("/"));
 String sNodeInstance =
   appName.substring(appName.indexOf("/") + 1, appName.length());
 sNodeInstance = sNodeInstance.replace('/', '.');
 txFactory = (ArmTransactionFactory)                   
 newObjectInstance("org.opengroup.arm40.sdk.ArmTransactionFactoryImpl");
 ArmApplication app = null; // 149297
 ArmApplicationDefinition appDef = null; //LIDB3207
 appDef =    txFactory.newArmApplicationDefinition(sWasName, null, null);
 app = txFactory.newArmApplication(appDef, sCellName, sNodeInstance, null);

 String[] idnames = { "request_type" };
 String[] idvalues = { "URI" };
 String[] ctxnames = { "URI" };
 ArmIdentityPropertiesTransaction props =
   txFactory.newArmIdentityPropertiesTransaction(
     idnames,
     idvalues,
     ctxnames,
     null);
 ArmTransactionDefinition atd =
    txFactory.newArmTransactionDefinition(
     appDef,
     "URI",
     props,
     (ArmID) null);
 ArmTransaction at = txFactory.newArmTransaction(app, atd);
 return at;} catch (Exception e) {
 System.out.println(e);
 return null;}
}

private ArmCorrelator newArmCorr() {

 ArmTransactionFactory txFactory = null;
try {
 String sWasName = "WebSphere";
 String appName = "t23xpimage/t23xpimage/server1";
 txFactory =
 (ArmTransactionFactory) newObjectInstance("org.opengroup.arm40.sdk.ArmTransactionFactoryImpl");

 ArmCorrelator arc =txFactory.newArmCorrelator(
     PmiRmArmStack.peekTransaction().getCorrelatorBytes());
 return arc;} catch (Exception e) {
 System.out.println(e);
 return null;}
}

IBM recommends using the HPEL log and trace infrastructure. With HPEL, one views logs using the LogViewer command-line tool in PROFILE/bin.

There are several potential scenarios for using the PmiRmArmStack. This example shows a scenario where code accesses an existing PmiRmArmTx on the stack, extracts the correlator, and calls blocked and unblocked. This is a typical scenario when sending a correlator along an unsupported protocol. In this scenario, the Arm transaction is already on the stack. 

1   PmiRmArmTx artrax =
2    PmiRmArmStack.peekTransaction();
3   if( artrax != null )
4                         {
5                                     try 6                                     {
7        byte[] cbytes = artrax.getCorrelatorBytes();
8                                         stuffBytesIntoOutboundMessage( msg, cbytes);
9                                          long blockedId = 0;
10                                         try 11                                         {
12                                            blockedId = artrax.blocked();
13                                          }
14                                          catch( NoSuchMethodException nsme )
15                                          {
16                                              // must not be running ARM4 or eWLM
17                                          }
18                                            sendMsg( msg );
19                                         try 20                                         {
21                                            artrax.blocked( blockedId );
22                                          }
23                                          catch( NoSuchMethodException nsme )
24                                          {
25                                              // must not be running ARM4 or eWLM
26                                          }
27                     
28                                      }
29                                      catch( Exception e )
30                                      {
31                                         report a problem;
32                                      }
33   }


Related


Monitor application flow
Troubleshoot applications with HPEL


+

Search Tips   |   Advanced Search