Oracle ATG Web Commerce - Performance Monitor API

Performance Monitor API

The main class for the Performance Monitor is atg.service.perfmonitor.PerformanceMonitor. This class contains all the static methods for interacting with the Performance Monitor. In addition, it stores the data structures that contain the performance data. The Performance Monitor’s methods have the following functions:

The PerformanceMonitor component contains two primary data structures. One stores the runtime stack data for all registered threads. The other stores the performance data for operations and parameterized operations on those registered threads.

Runtime Stack Data Structure
This structure is a Hashtable where the key is a registered thread and the element is a java.util.Stack of atg.service.perfmonitor.PerformanceStackData objects. This data is what is recorded and tracked in NORMAL mode. When a stack becomes empty, then all the performance operations have completed in that thread. This data structure is used in all modes except for DISABLED.

Performance Data Structure
This data structure stores all the time and memory performance related data for operations and parameterized operations. It is only used when the mode for the Performance Monitor is set to TIME or MEMORY. The structure is a Hashtable where the key is an operation name and the element is a PerformanceHashtable. The PerformanceHashtable is a subclass of Hashtable. In addition to providing the services of a Hashtable, it also stores the totals for all the parameterized operations contained in the Hashtable in an atg.service.perfmonitor.PerformanceData object. The Hashtable in the superclass of this object contains the parameterized operation name in the key and a PerformanceData object as the element.

There are also two data structures for holding pools of PerformanceStackData and PerformanceData objects. These exist to avoid allocation and improve performance. When startOperation is called, a new PerformanceStackData object is retrieved from the pool, populated and pushed on the stack. When endOperation is called, the top element in the stack is compared for mismatch and then popped off the stack, assuming there was no mismatch. At this time, the corresponding PerformanceData object for the operation in the PerformanceStackData object which is stored in the performance data structure is updated with number of times executed and total execution time (min and max will also be updated if the most current execution requires it). In addition, the global PerformanceData object for the operation is updated. If endOperation was called with no parameterized data, then only the global PerformanceData object for the operation is updated. If the PerformanceData object for the operation or parameterized data does not exist, then a new PerformanceHashtable will be created and PerformanceData object will be retrieved from the pool and inserted.

Methods for Controlling the Performance Monitor

You can control the Performance Monitor programmatically using the methods listed in this section. Most often, however, you will configure the Performance Monitor using the Performance Monitor Configuration page in the Dynamo Server Admin (http://hostname:port/dyn/admin/atg/dynamo/admin/en/performance-monitor-config.jhtml) or through the ACC.

public int getMode();
Returns the mode that the Performance Monitor is running in. The return value is an int that refers to one of DISABLED, NORMAL, TIME, or MEMORY.

public void setMode(int pMode);
Allows a user to dynamically set the mode of the Performance Monitor. The mode is normally set in the Performance Monitor’s properties file, but can be changed during runtime using the ACC.

public void resetPerformanceData();
Resets all the performance data back to 0. This means that the TIME mode and MEMORY mode minimum, maximum, and total statistics will be reset to 0 for all operations and parameterized operations.

Methods for Storing Performance Data

The startOperation and endOperation methods designate the start and end of an operation. These methods need to bracket the code that performs the designated function.

public static final void PerformanceMonitor.startOperation
(String pOpName);

public static final void PerformanceMonitor.startOperation(String pOpName, String pParameter);

The startOperation method tells Performance Monitor that a new operation is starting. The pOpName parameter is the name of the operation. This parameter should be short and as descriptive as possible. The next parameter, pParameter, is optional data that gives the Performance Monitor more detailed information on exactly what object it is performing the given operation on. The parameterized version of this method records data for the operation on the given parameter and the global operation. The non-parameterized version of this method records performance data to the operational level only.

public static final void PerformanceMonitor.endOperation(String pOpName)
     throws PerfStackMismatchException;

public static final void PerformanceMonitor.endOperation(String pOpName,
     String pParameter) throws PerfStackMismatchException;

public static final void PerformanceMonitor.endOperation();

The endOperation method tells Performance Monitor that a previously started operation has come to completion. The pOpName parameter must be exactly the same as the pOpName parameter that was passed into the corresponding startOperation method. The pParameter is optional data which gives the Performance Monitor more detailed information on the object it completed the operation on. The call to endOperation must have exactly the same parameters that the call to startOperation did. Otherwise, a PerfStackMismatchException (an extension of RuntimeException) is thrown.

You can also call endOperation without any arguments to mark the end of the most recent operation for which monitoring has started, but not yet ended. In this case, there is no need to supply it with the same arguments that were passed at the start of the operation. Accordingly, it will never throw an exception.

The cancelOperation method cancels an operation and discards any performance statistics.

public static final void PerformanceMonitor.cancelOperation(String
     pOpName) throws PerfStackMismatchException;

public static final void PerformanceMonitor.cancelOperation(String
     pOpName, String pParameter) throws PerfStackMismatchException;

The cancelOperation method tells Performance Monitor that a previously started operation should be cancelled. Canceling an operation means that statistics from this operation execution are discarded. The pOpName parameter must be exactly the same as the pOpName parameter that was passed into the corresponding startOperation method. The pParameter is optional data which gives the Performance Monitor more detailed information on the object on which it completed the operation. The call to cancelOperation must have exactly the same parameters that the call to startOperation did. Otherwise, a PerfStackMismatchException is thrown.

The isEnabled method indicates whether the Performance Monitor is enabled or not.

public static final boolean PerformanceMonitor.isEnabled();

Returns a boolean that specifies whether the Performance Monitor is enabled or not.

Methods for Accessing Stack Data

The stack data contains the runtime location of all the threads currently registered in the Performance Monitor. This data is stored in objects of type PerformanceStackData. The PerformanceStackData object is contained in a java.util.Stack object. The PerformanceStackData object alone is not useful; it becomes useful when it is placed inside the context of a java.util.Stack. The PerformanceStackData has the following methods you can use:

public String getOperation();
Returns the operation name within the PerformanceStackData object.

public String getParameter();
Returns the parameter operation name within the PerformanceStackData object.

public long getStartTime();
Returns the start time of the operation as the number of milliseconds since Jan 1, 1970. This method is used internally by the Performance Monitor and is not very useful outside of it, but it is provided.

Methods for Accessing Performance Data

The performance data is stored in read-only properties in objects of type PerformanceData. This object is a JavaBean that contains the following data:

Property	Description
`minimumExecutionTime`	Minimum execution time
`maximumExecutionTime`	Maximum execution time
`totalNumberOfExecutions`	Number of times operation has been executed
`averageExecutionTime`	Total execution time
`minimumMemoryRequired`	Minimum memory required
`maximumMemoryRequired`	Maximum memory required
`totalMemoryRequired`	Total memory required

The PerformanceData object has get methods that correspond to each of these properties. The average execution time and memory required can be derived from number of times and total execution time or memory required.

Exception Summary

PerfStackMismatchExceptionThrown when endOperation is called with out of order arguments or different arguments than what was expected.