Previous Topic: Agent Discovery APIsNext Topic: Agent VSE APIs


Agent Transaction APIs

Note: You can view detailed information about these classes in the JavaDocs for the agent. The JavaDocs are located in the LISA_HOME\doc directory.

A transaction is a code path executed by one or more servers as the result of a client request. A transaction is represented by a tree structure that is rooted at the client initiating the request. The nodes of the tree are com.itko.lisa.remote.transactions.TransactionFrame objects. These objects encapsulate information about a class, method, and arguments that were invoked as part of the server processing. Frames also contain ancillary information, such as the duration, the time of execution, and the thread in which it occurred.

You can think of a transaction as a method call stack. One difference is that transactions cross thread, process, or even computer boundaries. Another difference is that stacks contains all of the methods involved in the code execution of a thread, whereas transactions skip some levels and have frames only for chosen methods of interest. Such methods are referred to as intercepted methods.

The main way to obtain and work with TransactionFrame objects is through a few overloads of the following APIs supplied by com.itko.lisa.remote.client.TransactionsClient, which in turn can be obtained with the following call: AgentClient.getInstance().getTransactionsClient().

/**
  * Start recording transactions
  * @param info the agent to start recording on
  */
 public void startXRecording(IAgentInfo info) throws JMSInvocationException;
 
 /**
  * Stop recording transactions
  * @param info the agent to stop recording on
  */
 public void stopXRecording(IAgentInfo info) throws JMSInvocationException;
 
 /**
  * Start tracking socket usage on the client to use in reconciling client and server transactions.
  * This must be called prior to the call we're adding in addClientTransaction.
  * @param global install on all sockets or only on this thread
  */
 public void installSocketTracker(boolean global);
 
 /**
  * Stop tracking socket usage on the client to use in reconciling client and server transactions.
  * This should be called after the call we're adding in addClientTransaction.
  * @param global uninstall on all sockets or only on this thread
  */
 public void uninstallSocketTracker(boolean global);
 
 /**
  * As a client, you can invoke this method to root a transaction tree at a new client transaction created using
  * the specified parameters.
  * Note: you must call installSocketTracker before you initiate the client side transaction you're adding here
  * and it is recommended you call uninstallSocketTracker after you're done with the network call.
  * @param stamp     a unique string you can later use to identify the root transaction
  *      (in calls to getTransactions for ex.)
  * @param stepInfo  a nice human-readable string that tells what the transaction is doing (can be null)
  * @param args      the parameters the client passes to the transaction (can be empty)
  * @param result    the result of the transaction (can be null)
  * @param duration  the client's view of the transaction duration
  */
 public void addClientTransaction(String  stamp, String stepInfo, Object[] args, Object result, long duration);
 
 /** Delete all transactions and dependent data that originated from this client. */
 public void clearTransactions();
 
 /**
  * Gets a flat list of TransactionFrames received from all agents that satsfy the filters passed as arguments
  * @param offset    offset
  * @param limit     max number of results
  * @param category  filter by transaction category (see TranactionFrame.CATEGORY_XXX - 0 for no filter)
  * @param clazz     filter by class name (null or "" for no filter)
  * @param method    filter by method name (null or "" for no filter)
  * @param minTime   filter by frame duration greater than minTime
  * @return          a list of TransactionFrames satisfying the supplied criteria ordered by decreasing time
  */
 public List getTransactions(int offset, int limit, int category, String clazz, String method, int minTime);
 
 /**
  * Get a list of transaction trees rooted at the specified transaction(s) and satisfying the specified criteria
  * @param offset    offset
  * @param limit     max number of results
  * @param stamps    an array of root client transaction stamps - returns all if this is empty
  * @param minTime   duration below which transactions are pruned out of the results
  * @return ret      a list of transaction trees matching the criteria ordered by decreasing time
  */
 public List getTransactionsTree(int offset, int limit, String[] stamps, int minTime)

The parameters to these APIs do not specify an Agent or AgentInfo because transactions can span multiple agents.

Those APIs return lists of com.itko.lisa.remote.transactions.TransactionFrame (or trees thereof), so let us look at what data they encapsulate:

/** A unique identifier for this frame */
 public String getFrameId();
 public void setFrameId(String frameId);
 
 /** The frame id of this frame's parent frame
 public String getParentId();
 public void setParentId(String parentId);
 
 /** An identifier shared by all frames belonging to the same transaction (same as global root frame id) */
 public String getTransactionId();
 public void setTransactionId(String transactionId);
 
 /** The parent TransactionFrame object */
 public TransactionFrame getParent();
 public void setParent(TransactionFrame parent);
 
 /** The list of child TransactionFrame objects */
 public List getChildren();
 public void setChildren(List children);
 
 /** The unique identifier of the Agent this frame was recorded in */
 public long getAgentGuid();
 public void setAgentGuid(long agentGuid);
 
 /** Increasing counter that helps order the frames (time may not be precise enough) */
 public long getOrdinal();
 public void setOrdinal(long ordinal);
 
 /** Network incoming or outgoing frames set this to tell us what IP they are talking from */
 public String getLocalIP();
 public void setLocalIP(String ip);
 
 /** Network incoming or outgoing frames set this to tell us what port they are talking from */
 public int getLocalPort();
 public void setLocalPort(int port);
 
 /** Network incoming or outgoing frames set this to tell us what IP they are talking to */
 public String getRemoteIP();
 public void setRemoteIP(String ip);
 
 /** Network incoming or outgoing frames set this to tell us what port they are talking to */
 public int getRemotePort();
 public void setRemotePort(int port);
 
 /** The name of the thread this frame was recorded in */
 public String getThreadName();
 public void setThreadName(String threadName);
 
 /** Name of the class or interface this frame was recorded in (as per the interception spec) */
 public String getClassName();
 public void setClassName(String className);
 
 /** Name of the class of the actual object this frame was recorded in */
 public String getActualClassName();
 
 /** Name of the method this frame was recorded in */
 public String getMethod();
 public void setMethod(String method);
 
 /** Signature of the method this frame was recorded in */
 public String getSignature();
 public void setSignature(String signature);
 
 /** Formatted representation of the object this frame was recorded in */
 public String getSource();
 public void setSource(Object source);
 
 /** Formatted representation of the arguments to the method this frame was recorded in */
 public String[] getArguments();
 public void setArguments(Object[] arguments);
 
 /** Formatted representation of the result of the method this frame was recorded in */
 public String getResult();
 public void setResult(Object result);
 
 /** Number of times this frame was duplicated within its parent */
 public long getHits();
 public void setHits(long hits);
 
 /** Server time at which the frame was recorded */
 public long getTime();
 public void setTime(long time);
 
 /** Wall clock duration this frame took to execute */
 public long getClockDuration();
 public void setClockDuration(long clockDuration);
 
 /** CPU duration this frame took to execute */
 public long getCpuDuration();
 public void setCpuDuration(long cpuDuration);
 
 /** Custom representation of state associated with this frame */
 public String getState();
 public void setState(Object state);
 
 /** Formatted LEK info as encoded/decoded by the LEKEncoder class */
 public String getLekInfo();
 public void setLekInfo(String lekInfo);
 
 /** Pre-computed category this frame belongs to - see TransactionFrame.CATEGORY_XXX */
 public int getCategory();
 public void setCategory(int category);
 
 /** Bitwise or'ed combination of various internal pieces of information - see TransactionFrame.FLAG_XXX */
 public long getFlags();
 public void setFlags(long flags);