com.ibm.etools.logging.util
Class TimerStep

java.lang.Object
  |
  +--com.ibm.etools.logging.util.TimerStep
All Implemented Interfaces:
LoadValueConstants

public class TimerStep
extends java.lang.Object
implements LoadValueConstants

A class that knows how to time individual steps and also report on some operating system performance counters.

It is configured via an environment variable "etools_perf_ctrl". The value contains semicolon separated name value pairs. For example -Detools_perf_ctrl="log=X:\logs;sysout=true;testd=12"

The arguments, all of which are optional, are:

It can also be configured programatically.

Driver Info File

Often as you go through time you make changes to a driver. For example you replace the standard JRE with another, you apply certain patches, or you disable certain plugins. Often you have many drivers on a system and sometimes several systems. If you are not careful, it is easy to forget what changes have been made to any given driver. An effective technique to help with this problem is to record any changes that you make in a file that lives in the driver. Since these changes are also variations, it is useful to let the TimerStep class know about them so that they can be recorded as variations in the database. That is where the driverinfo argument comes in.

It points to a properties file that is usually placed in the driver install directory. For example driverinfo=u:\wsad50\DriverInfo.properties This file may include two properties:

When you make a change adjust the properties and add the approriate comments to the file. The variations in the driverinfo file and from the var argument in the etools_perf_ctrl environment variable are additive.

ivjperf.dll and psapi.dll

This class has some native methods that are supplied by the ivjperf or ivjperf2 dlls. These dlls rely on the psapi.dll from Microsoft. Unfortuneately Microsoft ships different versions of psapi.dll with different versions of Windows. The most complete version of psapi.dll comes with Windows XP or from the latest Platform SDK. The platform SDK is available via free download from http://www.microsoft.com/msdownload/platformsdk/sdkupdate/ IF you want the full function you will need to ensure that to the full function version of psapi.dll. The reason we ship two dlls (ivjperf and ivjperf2) is because of the different levels of function in psapi. Ww first try to load ivjperf and if that fails we try ivjperf2 which is a degraded version of the ivjperf dll.

Version:
$Revision: 1.1.14.1 $

Nested Class Summary
static class TimerStep.PerformanceInfo
          Hold some Window's global performance counters.
 
Field Summary
static java.lang.String GK_VERSION
           
 
Fields inherited from interface com.ibm.etools.logging.util.LoadValueConstants
ARG_GC_ELAPSED, ARG_GC_STEPS, ARG_INSTALLABLE, ARG_RUNTYPE_COLD, ARG_RUNTYPE_WARM, DIR_AUTOTEST_LOGS, ENV_ARG_TRUE, ENV_PARM_DRIVER_INFO, ENV_PARM_LOG, ENV_PARM_PAUSE, ENV_PARM_SYSOUT, ENV_PARM_TESTD, ENV_PARM_VAR, ENV_PERF_CTRL, ENVP_LOG_FILE, PARM_COMMENT, PARM_DRIVER, PARM_GC, PARM_GC_TYPE, PARM_HOST, PARM_JVM, PARM_RUN_TS, PARM_START_UP, PARM_STDOUT, PARM_STEP, PARM_TEST, PARM_TIMER_STEP, PARM_UUID, PARM_VAR, WHAT_CPU_TIME, WHAT_ELAPSED, WHAT_KERNEL_TIME, WHAT_TOTAL_JAVA_HEAP, WHAT_USED_JAVA_HEAP, WHAT_USER_TIME, WHAT_WS_PEAK
 
Constructor Summary
TimerStep()
          In the normal case, only a single TimerStep would be allocated, so plugins need to be careful that any one plugin doesn't allocated more than one timer.
 
Method Summary
 void chgVar(java.lang.String var)
          Change the variation, and if it has changed from its previous setting write the new value out to the log.
static java.lang.String[] countersAsStrings(long[] counters, boolean skipElasped)
          Answer the process counters in a human readable form.
static java.lang.String formatedTime(long diff)
          Answer a formated string for the elapsed time (minutes, hours or days) that is appropriate for the scale of the time.
static java.lang.String formatEng(long n)
          Answer a number formated using engineering conventions, K thousands, M millions, G billions and T trillions.
 boolean getAutoMemory()
          Answer the auto memory setting.
 java.lang.String getLogFile()
          Answer the location of the performance measurement file (a.k.a the timer.del file).
 java.lang.String getPendingDriver()
          Answer the pending driver name.
static TimerStep.PerformanceInfo getPerformanceInfo()
          Answer some system wide performance information.
 boolean getSysout()
          Answers the sysout preference.
 int getTestd()
          Answer the test case number that the performance measurements are associated with.
 java.lang.String getTestdAdhoc()
          If this is an adhoc test answer the test description, otherwise answer the test number.
 java.lang.String getVar()
          Answer the variations that are in effect as a comma delimited string.
 boolean hasTest()
          Answer true if a test has been specified.
static TimerStep instance()
          Answer your singleton instance, although this class need not be used as a true singleton.
 boolean is_pause()
          Deprecated.  
 boolean isHumanReadable()
          Answer the human readable setting.
 boolean isLogFileEnv()
          Has the logfile been set via an environment variable?
 boolean isOn()
           
 boolean isTestdEnv()
          Has the testcase number been set via an environment variable?
 boolean isVarEnv()
          Have the variations been set via an environment variable?
static void main(java.lang.String[] args)
          Print the version of this class to stdout.
static void reset()
          Reset the singleton instance of the timer, this will force the next instance() method to recreate and reinitialize the timer.
 void reset(int timerNumber)
          Reset the timer to the current time.
static boolean same(java.lang.String s1, java.lang.String s2)
          A helper method that answers true if the two Strings are equal.
 void set_pause(boolean _pause)
          Deprecated.  
 void setAndWriteVar(java.lang.String var)
          Update the variation, and if it has changed then write the change into the timer file.
 void setAutoMemory(boolean autoMemory)
          Should we write out the windows performance counters and the size of the total heap on the timer writes? The default is yes.
 void setHumanReadable(boolean humanReadable)
          Set the human readable setting.
 void setIsOn(boolean isOn)
          Set the TimerStep to be on or off.
 void setLogFile(java.lang.String logFile)
          Set the location of the performance measurement file, that is the place where the measurements are stored.
 void setPendingDriver(java.lang.String pendingDriver)
           
 void setSysout(boolean sysout)
          Sets the sysout preference.
 void setTestd(int testd)
          Sets the testcase number for this measurement run.
 void setTestdAdhoc(java.lang.String testdAdhoc)
          Update the test, if it is only a number than this is the same as calling setTestd otherwise it is treated as a true adhoc test.
 void setVar(java.lang.String var)
          Set the variations that are in effect.
 void totalMemory(int step)
          Deprecated. Use totalMemory2
 long totalMemory2(int step)
          Write out the size of the Java Heap.
 void usedMemory(int step)
          Deprecated. Use usedMemory2(int step)
 long usedMemory2(int step)
          Write out how much of the Java heap is being used.
 void write(int timerNumber, int step)
          Write the elapsed time for a particular timer to the timer log.
 void write(java.lang.String line, java.lang.String prefix)
          Write the line out to the log, with a prefix.
 void writeAndReset(int timerNumber, int step)
          Write the elapsed time for a particular timer and reset the timer.
 void writeComment(java.lang.String comment)
          Write the comment to the performance measurement file.
 TimerStep.PerformanceInfo writeCommittedMemory(int step)
          Write out the committed memory measurements.
 void writeCounters(int step)
          Deprecated. Use writeCounters2
 void writeCounters(int step, boolean skipElasped)
          Deprecated. Use writeCounters2
 long[] writeCounters2(int step)
          Write out the process based performance counters from the operating system.
 long[] writeCounters2(int step, boolean skipElasped)
          Write out the performance counters from the operating system.
 void writeEnvironment(java.lang.String driver)
          Write the machine name and driver level in the timer file.
 TimerStep.PerformanceInfo writePerformanceInfo(int step)
          Write out the global performance info.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

GK_VERSION

public static final java.lang.String GK_VERSION
See Also:
Constant Field Values
Constructor Detail

TimerStep

public TimerStep()
In the normal case, only a single TimerStep would be allocated, so plugins need to be careful that any one plugin doesn't allocated more than one timer. We make this public because we are not strictly following the singleton pattern, but the preferred method is still to use the instance() method.

See Also:
instance()
Method Detail

main

public static void main(java.lang.String[] args)
Print the version of this class to stdout.


instance

public static TimerStep instance()
Answer your singleton instance, although this class need not be used as a true singleton. This is the preferred way to get a TimerStep.


reset

public static void reset()
Reset the singleton instance of the timer, this will force the next instance() method to recreate and reinitialize the timer. This method is often called after we have uploaded a timer.del file and want to ensure that new headers are loaded into the next timer.del file. Calling this method starts a new run, so please ensure that is what you want before calling this method.


chgVar

public void chgVar(java.lang.String var)
Change the variation, and if it has changed from its previous setting write the new value out to the log.


getPerformanceInfo

public static TimerStep.PerformanceInfo getPerformanceInfo()
Answer some system wide performance information. The returned field message must be null in order for the results to be valid, otherwise message holds an error message. If you have an older version of psapi.dll on your system this method will return an error message.


reset

public void reset(int timerNumber)
Reset the timer to the current time.

Parameters:
timerNumber - the timer that we are resetting;

same

public static boolean same(java.lang.String s1,
                           java.lang.String s2)
A helper method that answers true if the two Strings are equal. If they are both null then they are considered equal.


totalMemory

public void totalMemory(int step)
Deprecated. Use totalMemory2

Write out the size of the Java Heap. This is the same as totalMemory2 expect it doesn't return a value.


totalMemory2

public long totalMemory2(int step)
Write out the size of the Java Heap.

Returns:
the size of the Java Heap;

usedMemory

public void usedMemory(int step)
Deprecated. Use usedMemory2(int step)

Write out how much of the Java heap is being used. This calls the GC so it may skew timing results.


usedMemory2

public long usedMemory2(int step)
Write out how much of the Java heap is being used. This calls the garbage collector so it may skew timing results.

Returns:
the used memory

write

public void write(int timerNumber,
                  int step)
Write the elapsed time for a particular timer to the timer log. This is a comma separated value in the form testid, runid, step, what, result

Parameters:
timerNumber - the timer number
step - the step id, this corresponds to an entry in the tmr.stepd table

write

public void write(java.lang.String line,
                  java.lang.String prefix)
Write the line out to the log, with a prefix.

Parameters:
line - the line that you want to write out
prefix - a prefix that you want to write out before the line. For example it would be common to set this to a variable name like "Test=".

writeEnvironment

public void writeEnvironment(java.lang.String driver)
Write the machine name and driver level in the timer file. Normally you do not need to call this, as the driver information will be retrieved from the logging.util plugin

Parameters:
driver - the driver level, for example "20020426_1828-M5-V50R". This usually comes from the BuildInfo.level()

writePerformanceInfo

public TimerStep.PerformanceInfo writePerformanceInfo(int step)
Write out the global performance info. This includes things like the total committed memory for the entire system.

Parameters:
step -
Returns:
performance info structure

writeCommittedMemory

public TimerStep.PerformanceInfo writeCommittedMemory(int step)
Write out the committed memory measurements.

Parameters:
step -
Returns:
performance info structure

writeAndReset

public void writeAndReset(int timerNumber,
                          int step)
Write the elapsed time for a particular timer and reset the timer.


writeComment

public void writeComment(java.lang.String comment)
Write the comment to the performance measurement file.

Parameters:
comment -

writeCounters

public void writeCounters(int step)
Deprecated. Use writeCounters2

Write out the process based performance counters from the operating system. These include working set, peak working set, elapsed time, user time, and kernel time.


writeCounters2

public long[] writeCounters2(int step)
Write out the process based performance counters from the operating system. These include working set, peak working set, elapsed time, user time, and kernel time.


writeCounters

public void writeCounters(int step,
                          boolean skipElasped)
Deprecated. Use writeCounters2

Write out the process based performance counters from the operating system. These include working set, peak working set, elapsed time, user time, and kernel time.

Parameters:
skipElasped - this controls whether the elasped time should be included or not. For tests that are performed by a human this value doesn't usually make make much sense.
Returns:
an array of counters. Return null if the TimerStep is not enabled.

writeCounters2

public long[] writeCounters2(int step,
                             boolean skipElasped)
Write out the performance counters from the operating system. These include working set, peak working set, elapsed time, user time, and kernel time.

Parameters:
skipElasped - this controls whether the elasped time should be included or not. For tests that are performed by a human this value doesn't usually make make much sense.
Returns:
an array of counters. Return null if the TimerStep is not enabled.

countersAsStrings

public static java.lang.String[] countersAsStrings(long[] counters,
                                                   boolean skipElasped)
Answer the process counters in a human readable form.

Parameters:
counters - the array of counters
skipElasped - are we skipping the elasped time counter?
Returns:
each counter as its own human readable string.

formatEng

public static java.lang.String formatEng(long n)
Answer a number formated using engineering conventions, K thousands, M millions, G billions and T trillions. I copied this method from karasiuk.utility.Misc.


formatedTime

public static java.lang.String formatedTime(long diff)
Answer a formated string for the elapsed time (minutes, hours or days) that is appropriate for the scale of the time.

Parameters:
diff - time in milliseconds I copied this from karasiuk.utility.TimeIt

getSysout

public boolean getSysout()
Answers the sysout preference. If true it means that measurement information is also echoed to sysout.


setSysout

public void setSysout(boolean sysout)
Sets the sysout preference.

Parameters:
sysout - If set to true the measurement information will also be echoed to sysout.

getAutoMemory

public boolean getAutoMemory()
Answer the auto memory setting. If this setting is true it means we will write out the memory counters on the timer writes.


setAutoMemory

public void setAutoMemory(boolean autoMemory)
Should we write out the windows performance counters and the size of the total heap on the timer writes? The default is yes. (This does not include calling the usedMemory() method since that would have forced a GC).

See Also:
write(int, int)

is_pause

public boolean is_pause()
Deprecated.  

Answer the pause setting. If this is set to true we pause before writing out the counters. This gives us a chance to jinsight to the process.


set_pause

public void set_pause(boolean _pause)
Deprecated.  

Set the pause setting. If this is set to true we pause before writing out the counters. This gives us a chance to jinsight to the process.


getTestd

public int getTestd()
Answer the test case number that the performance measurements are associated with.


getVar

public java.lang.String getVar()
Answer the variations that are in effect as a comma delimited string.


setTestd

public void setTestd(int testd)
Sets the testcase number for this measurement run.

Parameters:
testd -

setVar

public void setVar(java.lang.String var)
Set the variations that are in effect.

Parameters:
var - a comma delimited string of variation numbers

setAndWriteVar

public void setAndWriteVar(java.lang.String var)
Update the variation, and if it has changed then write the change into the timer file.

Parameters:
var - the new varaitions that are in effect

isOn

public boolean isOn()

setIsOn

public void setIsOn(boolean isOn)
Set the TimerStep to be on or off. If it is off then most of the other operations will no-op. Normally this method doesn't need to be called. The default is for the TimerStep to be off unless it's special environment variable is set.


isHumanReadable

public boolean isHumanReadable()
Answer the human readable setting. If true we also generate human readable measurements (as comments) into the performance file.


setHumanReadable

public void setHumanReadable(boolean humanReadable)
Set the human readable setting. If true we also generate human readable measurements (as comments) into the performance file.


getLogFile

public java.lang.String getLogFile()
Answer the location of the performance measurement file (a.k.a the timer.del file).


setLogFile

public void setLogFile(java.lang.String logFile)
Set the location of the performance measurement file, that is the place where the measurements are stored.

Parameters:
logFile -

getPendingDriver

public java.lang.String getPendingDriver()
Answer the pending driver name. This is the driver name that we use if this class is "turned on" later.


setPendingDriver

public void setPendingDriver(java.lang.String pendingDriver)

getTestdAdhoc

public java.lang.String getTestdAdhoc()
If this is an adhoc test answer the test description, otherwise answer the test number.


hasTest

public boolean hasTest()
Answer true if a test has been specified. This can be either an adhoc test or a real test.


setTestdAdhoc

public void setTestdAdhoc(java.lang.String testdAdhoc)
Update the test, if it is only a number than this is the same as calling setTestd otherwise it is treated as a true adhoc test.

Parameters:
testdAdhoc -

isLogFileEnv

public boolean isLogFileEnv()
Has the logfile been set via an environment variable?


isTestdEnv

public boolean isTestdEnv()
Has the testcase number been set via an environment variable?


isVarEnv

public boolean isVarEnv()
Have the variations been set via an environment variable?