Class next.wo.StatisticsStore

CLASS DESCRIPTION

Extends:
next.util.NextObject

The StatisticsStore object records statistics about a WebObjects application while that application runs. All WebObjects applications have a StatisticsStore object, which you can access by sending statisticsStore to the WebApplication object. If the application is linked to the WOExtensions framework (which occurs by default if you use Project Builder to create the application), it contains a component named WOStats, which displays the statistics recorded by StatisticsStore. To access an application's WOStats page, use a URL such as this one:

http://localhost/cgi-bin/WebObjects/HelloWorld.woa/-/WOStats

or:

http://localhost/cgi-bin/WebObjects/HelloWorld.woa/-/WOStats.wo/-/-/1/myHost

where the number 1 in the URL above is the application's instance number.

For more information on what the WOStats page displays, see its description in the online book WebObjects Extensions Reference.

Recording Information

The StatisticsStore object records the bulk of its statistics at the end of each cycle of the request-response loop. Specifically, at the end of WebSession's appendtoResponse method, the WebSession sends the recordStatisticsForResponse message to the StatisticsStore. This message tells the StatisticsStore to begin recording statistics. Then, WebSession sends it a descriptionForResponse message. This method sends the response component a descriptionForResponse message. The default implementation of descriptionForResponse in Component returns the component's name.

You can override descriptionForResponse in each of your components if you want to record more information. For example, you might want to record the values of all of the component's variables or perhaps just one or two key variables.

If you want to record extra information about the session, you can override StatisticsStore's recordStatisticsForResponse method.

Maintaining a Log File

You can maintain an application log file by sending the message setLogFile to the StatisticsStore object. When a log file has been specified, each session records information in the log file about the pages it accessed. The log is maintained in Common Log File Format (CLFF) so that it can be analyzed by any standard CLFF-analysis tool. (For more information about the statistics recorded in the log file, see the formatDescription method description.) If a log file has been specified, the WebSession object keeps its own statistics about which pages it has accessed. When the session terminates, it writes this information to the log file.

The Statistics Dictionary

If you want to retrieve statistics programmatically, you can do so by sending the StatisticsStore a statistics message. This returns a dictionary object, which has the following keys:

StartedAt
The date and time at which this application instance was launched.

LogFile
The name of the CLFF-formatted log file recording session statistics. This log file does not exist unless you create it by sending setLogFile to the StatisticsStore.

Transactions
A dictionary of statistics about the request-response loop transactions. The keys into this dictionary are:
Transactions
Total number of transactions processed by this application instance.
Avg. Idle Time
Average length of time the application sat idle between transactions.
Moving Avg. Idle Time
Average length of time the application sat idle between the last n transactions, where n is the number returned by movingAverageSampleSize.
Avg. Transaction Time
Average length of time it took to process a transaction.
Moving Avg. Transaction Time
Average length of time it took to process the last n transactions, where n is the number returned by movingAverageSampleSize.
Sample Size For Moving Avg.
The moving average sample size.

Sessions
A dictionary of statistics about sessions of the application. The keys into this dictionary are:
Total Sessions Created
The total number of sessions created by this application instance.
Current Active Sessions
Number of the created sessions that are still active.
Peak Active Sessions
The maximum number of sessions that have been active at the same time.
Peak Active Sessions Date
Date and time at which the peak number of active sessions occurred.
Avg. Transactions Per Session
The average number of transactions each user performed in a session.
Avg. Session Life
Average length of time a user session lasted.
Avg. Memory Per Session
A dictionary containing average session memory usage statistics. The keys into this dictionary are the same as to the application's Memory dictionary.
Last Session's Statistics
If a session has expired, a list of the pages that the last session accessed, listed from first to last accessed. By default, only the page names are recorded, but you may override Component's descriptionForResponse method to provide more information.

Memory
A dictionary of memory usage statistics. The keys into this dictionary are:
Committed
Amount of memory committed to this application (Windows NT platform only).
Reserved
Amount of memory reserved by the application (Windows NT platform only).
Process Image Size
Amount of virtual memory the application uses (Solaris platform only).
Resident Set Size
Amount of physical memory the application uses (Mach and Solaris platforms).
Virtual
Amount of virtual memory the application uses (Mach platform only).

Pages
A dictionary of dictionaries containing access statistics for each page in the application. The keys into this dictionary are the pages that have been accessed so far. (Pages that haven't been accessed yet aren't in the dictionary, and components that represent only a portion of the page rather than the full page aren't in the dictionary.)

The keys into each page's dictionary are:

Served
The number of times a given page has been accessed.
Avg Resp. Time
Average amount of time it took to receive the request for this page, process the request, invoke the appropriate action in the request component, and generate this page. Often, the bulk of the time it takes to generate a page happens in the action invocation and response generations phases of the request-response loop. The initial processing of the request takes a minimal amount of time.

For example, suppose the user clicks a button in Page A that fetches items from a database and displays those items in Page B. The total amount of time it takes to handle the request on Page A, invoke the action, fetch items from the database, and generate Page B is recorded as the amount of time it took to generate Page B.

Min Resp. Time
The smallest amount of time it took to generate this page.
Max Resp. Time
The largest amount of time it took to generate this page.

METHODS

descriptionForResponse

public java.lang.String descriptionForResponse(next.wo.Response aResponse, next.wo.Context aContext)

Records information about the current response by sending the descriptionForResponse message to the response page and returning the result. This method is invoked at the end of the request-response loop in WebSession's appendToResponse method, after the recordStatisticsForResponse method.

See Also: descriptionForResponse (Component class)


formatDescription

public java.lang.String formatDescription(java.lang.String responseDescription, next.wo.Response aResponse, next.wo.Context aContext)

If log file recording is enabled, this method formats the string responseDescription in using Common Log File Format (CLFF). The resulting string contains:

You enable log file recording by setting a log file using the setLogFile method.

This method is used by WebSession to record information about the current transaction when log file recording is enabled.

See Also: logFile, logString


logFile

public java.lang.String logFile()

Returns the full path to the CLFF log file. This log file does not exist unless you send setLogFile to the StatisticsStore.

See Also: formatDescription, logFileRotationFrequencyInDays, logString


logFileRotationFrequencyInDays

public double logFileRotationFrequencyInDays()

The number of days a log file lasts. That is, a log file's contents are flushed after a certain time interval to ensure that it does not grow too large and a new log file is started. This method returns that time interval.

Before a new log file is started, the contents of the current log file are saved to a backup file. You can then inspect this log file and/or remove it when its data has grown stale.

See Also: setLogFile


logString

public void logString(java.lang.String aString)

Writes the string aString to the CLFF log file specified by logFile. The method is used to record a session's statistics when that session ends. You can also use it to record any string to the log file that might be helpful to you.

See Also: formatDescription


movingAverageSampleSize

public int movingAverageSampleSize()

Returns the sample size used to compute moving average statistics. The StatisticsStore object uses this sample size to compute the response time for the last n transactions and the idle time between the last n transactions, where n is the number returned by this method.

See Also: setMovingAverageSampleSize


recordStatisticsForResponse

public void recordStatisticsForResponse(next.wo.Response aResponse, next.wo.Context aContext)

Records statistics for the current cycle of the request-response loop. This method is invoked at the end of WebSession's appendToResponse method, immediately before the descriptionForResponse method. By default, this method records the name of the response page for later use by descriptionForResponse. You can override it if you want to record more information about the session before the current request and response are deallocated. You must begin your implementation by invoking the superclass method.


setLogFile

public void setLogFile(java.lang.String filePath, double logRotation)

Sets the full path of the log file to which CLFF statistics will be recorded to filePath. The logRotation argument specifies the number of days statistics will be recorded to this log file. Every logRotation days, the contents of the current log file are saved to a backup file and a new log file is started.

The default is not to record information to a log file.

See Also: logFile, logFileRotationFrequencyInDays


setMovingAverageSampleSize

public void setMovingAverageSampleSize(int aSize)

Sets the moving average sample size to aSize. The StatisticsStore object uses this sample size to compute the response time for the last aSize transactions and the idle time between the last aSize transactions.

The default moving average sample size is 100 transactions.

See Also: movingAverageSampleSize


setPassword

public void setPassword(java.lang.String aPassword)

Implements security for the WOStats page by setting its password to aPassword. By default, there is no password, so any user can access the WOStats page (provided they know the URL). If you implement this method, when you enter the WOStats URL, a login panel appears. You can leave the User name field blank; as long as you type the appropriate password in the password field, the WOStats page will appear.

See also: validateLogin


statistics

public next.util.ImmutableHashtable statistics()

Returns a dictionary containing the statistics that the StatisticsStore records. See the section The Statistics Dictionary in the class description for more information on the type of information recorded as well as the keys to this dictionary.


validateLogin

public boolean validateLogin(java.lang.String aString)

Returns true if aString is the password set by setPassword, and false otherwise. The password controls if the user can see the WOStats page.

See also: setPassword