org.jlf.vitals
Class VitalSignProperties

java.lang.Object
  |
  +--java.util.Dictionary
        |
        +--java.util.Hashtable
              |
              +--java.util.Properties
                    |
                    +--org.jlf.util.AppProperties
                          |
                          +--org.jlf.vitals.VitalSignProperties

All Implemented Interfaces:

java.lang.Cloneable, java.util.Map, java.io.Serializable

public class VitalSignProperties

extends AppProperties

This class is used to hold properties for a particular Vital Sign with a vitalsKey.

All properties for a VitalSign are prefixed by org.jlf.vitals.(vitalKey), where (vitalKey) is the string name of a uniquely-identified vital sign. Default properties for vital signs are shown below unless overriden by property file entries.

 org.jlf.vitals.(vitalKey).implementationClass=org.jlf.vitals.VitalSign
      - implementationClass is the fully-qualified Java class that
        is either the VitalSign (default) or subclass of VitalSign that
        implements the periodic measurement of the vital sign.
        This property is generally only useful for vital signs that
        are collected periodically and need code to implement that
        periodic measurement logic
 
 org.jlf.vitals.(vitalKey).measurementClass=org.jlf.vitals.LongVitalMeasurement
      - measurementClass is the fully-qualified Java class 
        that implements the measurement value(s) for this vital sign.
        The default is a simple long value (for example, to hold a count of
        the number of milliseconds to satisfy a request).

 org.jlf.vitals.(vitalKey).vitalName=(the vitalKey if not specified)
      - vitalName is a nice display name for the vital sign, if the vitalKey
        doesn't look good enough for display.  vitalKey must be unique
        for purposes of registering vital signs and managing their properties,
        but vital name does not.
 
 org.jlf.vitals.(vitalKey).measurementUnit=count
      - measurementUnit is a nice display name for the units measured for this
        vital sign.  Examples include requests per second, milliseconds to
        complete, bytes consumed.

 org.jlf.vitals.(vitalKey).measurementFrequencyInSeconds=0
      - measurementFrequencyInSeconds is how often the vitals manager
        must collect a measurement on this vital sign.  If this
        value is zero, the vital sign is not collected automatically
        (you must programmatically do the collection yourself). If
        this value is non-zero, then the vitals
        sampling thread kicks in every second, looks through any
        registered vital signs with a non-zero measurement
        frequency, checks the last time it was collected, and if
        not collected recently, asks that vital sign for a
        current measurement.  Note, don't count on the vital
        sampling thread to sample you every second, even if
        you set this setting to 1 second.  To avoid over-taxing
        the virtual machine, the sampling thread is going to kick
        in every second but depending upon its workload, it may or
        may not get around to you every single second.
 
 org.jlf.vitals.(vitalKey).refreshChildInstanceListInSeconds=120
      - refreshChildInstanceListInSeconds is how often the vitals manager
        will ask the vital sign to refresh its list of child instances.
        This is only applicable to a vital sign that has multiple instances
        for the same implementation.  For example, JDBC connection pools
        have the same vital statistic implementation, but different instances,
        one per connection pool.
 
 org.jlf.vitals.(vitalKey).alertAfterMinumumMeasurementsTaken=25
      - alertAfterMinumumMeasurementsTaken is the number of measurements
        that need to be collected before any logger alerts get logged.
        You probably need some kind of sampling in the program before
        you generate percentile based alerts or you will get false
        alerts until a baseline history can be established.
        If this property is set to zero, no alerts will ever be logged.
 
 org.jlf.vitals.(vitalKey).alertAtNewHigh=false
      - alertAtNewMaximum logs an alert if a measurement is taken
        that exceeds the highest previously recorded measurement
 
 org.jlf.vitals.(vitalKey).alertAtAveragePercentileExceeded=150
      - alertAtPercentileExceeded is the threshold that needs to
        be exceeded, as compared to the average measurement value
        for this statistic over time, for an alert to be logged.
        If this value is zero, no alert of this type will ever be generated.
 
 org.jlf.vitals.(vitalKey).alertAtMaximumAvailablePercentileExceeded=75
      - alertAtMaximumAvailablePercentileExceeded logs an alert if a 
        measurement is taken that exceeds a percentage of a hard 
        maximum value.  This alert is only available for subclasses
        of VitalSign that define hard maximum measures.  For example, 
        say you create a vital sign that monitors JDBC connection
        pool usage, and that connection pool has a hard maximum of
        20 JDBC connections.  You typically want to get proactively
        notified if that pool gets to 75% of its maximum to see what
        is going on for a pool that normal runs say 20% utilization,
        hopefully in time for you to rectify the situation before
        the pool maxes out and clients get exceptions trying to get
        a connection from the pool that is maxed out.  If this value
        is zero, no alert of this type will ever be generated.
 
 org.jlf.vitals.(vitalKey).recentMeasurementHistorySize=0
      - recentMeasurementHistorySize keeps a list of the given
        number of most recent measurements (be careful with this, 
        each measurement requirements a little bit of memory).  If
        set to zero, no recent measurement history will be kept
 
 org.jlf.vitals.(vitalKey).recentAlertHistorySize=20
      - recentAlertHistorySize keeps a list of the most
        recent measurements that caused an alert log
        entry to be generated (be careful with this, 
        each measurement requirements a little bit of memory).  If
        set to zero, no recent alert history will be kept.
 
 org.jlf.vitals.(vitalKey).alertFrequencyInSeconds=300
      - alertFrequencyInSeconds tells the frequency to log
        an alert.  If a condition exists where alerts are
        frequently created, this property correlates the alerts
        to they don't flood a log file (only one alert log
        is generated per x seconds set in this property)
 
 org.jlf.vitals.(vitalKey).loggingFrequencyInSeconds=0
      - loggingFrequencyInSeconds tells the frequency
        to log a recorded measurement.  Normally this would be
        set to zero, where the measurement is only logged if it is
        an alert.  However, sometimes it is valuable to be able to
        log a vital sign periodically throughout the day (but you
        don't want to flood the log).  So this setting, if larger than
        zero, will periodically log any recorded measurents to the Logger
        below at INFO level. 
 
 org.jlf.vitals.(vitalKey).logger=org.jlf.vitals.VitalsLogger
      - the name of the JDK logger that this vital sign should
        output to when an alert status is recognized.  Vitals are
        logged at WARNING level whenever a new maximum has been recorded
        that exceeds the percentile given above.
 

See Also:

VitalSign, AppProperties, Serialized Form

Field Summary

static long	ALERT_AT_AVERAGE_DEFAULT The class name of the AbstractVitalMeasurement subclass to use to record measurements for the vital sign.
static java.lang.String	ALERT_AT_AVERAGE_PROPERTY The name of the property to look up for the alertAtAveragePercentileExceeded property.
static long	ALERT_AT_MAX_PERCENT_DEFAULT The default value of the alert at max percentage property.
static java.lang.String	ALERT_AT_MAX_PERCENT_PROPERTY The name of the property to look up for the alert at max percentage property.
static long	ALERT_FREQUENCY_DEFAULT The default value of alert frequency, at a maximum, alert every 5 minutes.
static java.lang.String	ALERT_FREQUENCY_PROPERTY The name of the property to look up for the alert frequency
static java.lang.String	IMPLEMENTATION_CLASS_NAME_DEFAULT The default connectionInfoSourceClass name.
static java.lang.String	IMPLEMENTATION_CLASS_NAME_PROPERTY The name of the property to look up for the connectionInfoSourceClass name.
static java.lang.String	LOGGER_DEFAULT The default JDK logger VitalsLogger.
static java.lang.String	LOGGER_PROPERTY The name of the property to look up for the JDK logger.
static long	LOGGING_FREQUENCY_DEFAULT The default value for logging frequency, that is, no logs are generated by default.
static java.lang.String	LOGGING_FREQUENCY_PROPERTY The name of the property to look up for the logging frequency
static java.lang.String	MEASUREMENT_CLASS_DEFAULT The default measurement class for the vital sign.
static java.lang.String	MEASUREMENT_CLASS_PROPERTY The name of the property to look up for the measurement class for the vital sign.
static long	MEASUREMENT_FREQUENCY_DEFAULT The default value for measurement frequency.
static java.lang.String	MEASUREMENT_FREQUENCY_PROPERTY The name of the property to look up for the measurement frequency.
static java.lang.String	MEASUREMENT_UNIT_DEFAULT The default measure display name
static java.lang.String	MEASUREMENT_UNIT_PROPERTY The name of the property to look up for the measure display name.
protected java.lang.Class	measurementClass Holds a cached Class object (to save on reflection overhead) that is the equivalent of the measurement class above.
static long	MEASURMENT_HISTORY_DEFAULT The class name of the AbstractVitalMeasurement subclass to use to record measurements for the vital sign.
static java.lang.String	MEASURMENT_HISTORY_PROPERTY The name of the property to tell the size of the recently collected measurements queue.
static long	MINIMUM_MEASUREMENTS_DEFAULT The default minimum number of measurements.
static java.lang.String	MINIMUM_MEASUREMENTS_PROPERTY Property for minimum measurements taken before alerts logged.
static boolean	NEW_HIGH_DEFAULT The default value of the alertAtNewHigh property
static java.lang.String	NEW_HIGH_PROPERTY The name of the property to look up for the alertAtNewHigh setting.
static long	RECENT_ALERT_HISTORY_DEFAULT The default alert history size
static java.lang.String	RECENT_ALERT_HISTORY_PROPERTY The name of the property to look up for the alert history size
static long	REFRESH_INSTANCE_DEFAULT Default value for the refresh instance property.
static java.lang.String	REFRESH_INSTANCE_PROPERTY The name of the property to look up for the refresh instance frequency.
static java.lang.String	VITAL_NAME_PROPERTY The name of the property to look up for the nice display name of the vital sign.
protected java.lang.String	vitalKey Holds the Vital Sign unique key these properties are for
protected static java.lang.String	VITALS_KEY_PROPERTY_PREFIX Property prefix for all vital sign properties.

Fields inherited from class org.jlf.util.AppProperties

PROPERTY_FILE_COMPONENT_VERSION_PREFIX, propertyFileName, singleton

Fields inherited from class java.util.Properties

defaults

Constructor Summary

VitalSignProperties(java.lang.String vitalKey, java.util.Properties properties)
Passthrough constructor for dynamic properties (that is, properties which DON'T come from property files).

Method Summary

boolean	alertAtNewHigh() Returns the setting to see if an alert should be generated if a newly recorded measure is the high measure.
protected java.lang.Class	basicGetMeasurementClass() Helper method to return a measurement class
long	getAlertAfterMinimumMeasurementsTaken() Returns the minimum measurements taken before alerts logged.
long	getAlertAtAveragePercentileExceeded() Returns the percentage of average that, if exceeded, an alert will be generated.
long	getAlertAtMaximumAvailablePercentileExceeded() Returns the percentage that if a newly recorded measurement exceeds this percentage of the theoritical max for the vital sign, an alert will be generated.
long	getAlertFrequencyInSeconds() Returns the minimum time in seconds that can elapse between alerts getting logged.
java.lang.String	getImplementationClassName() Returns the name of the class that implements the vital sign.
static VitalSignProperties	getInstance(java.lang.String vitalKey) Factory method to retrieve a set of properties for the named vital sign.
java.lang.String	getLoggerName() Returns the JDK logger that will be used when logging measurements and alerts.
long	getLoggingFrequencyInSeconds() Returns the number of seconds between logging the currently recorded value of a captured vital sign measurement.
java.lang.Class	getMeasurementClass() Returns the class that should be used to hold measurements for the vital sign.
long	getMeasurementFrequencyInSeconds() Returns how often the vitals manager must collect a measurement on this vital sign.
java.lang.String	getMeasurementUnit() Returns the display name for the measure collected by the vital sign (for example, milliseconds elapsed, requests per second).
static java.util.Collection	getPeriodicVitalKeys() Helper method to look through all the properties in the property file and return the vitalKeys of anything that should be loaded for periodic collection.
long	getRecentAlertHistorySize() Returns the number of alerts generated that should be kept in memory as a history.
long	getRecentMeasurementHistorySize() Returns the length of the queue keeping the most recent measurements.
long	getRefreshChildInstanceListInSeconds() Returns how often a vital sign with child instances needs to see if new instances need to be created.
java.lang.String	getVitalName() Returns the nice display name of the vital sign.
boolean	shouldMeasureVitalSignPeriocially() Returns if the vital sign should be measured periodically (basically if measurement frequence greater than zero, then yes).

Methods inherited from class org.jlf.util.AppProperties

getBooleanProperty, getComponentsAndVersions, getInstance, getIntegerProperty, getLongProperty, getPropertiesForPrefix, getStringProperty, isRelativePathFileName, load

Methods inherited from class java.util.Properties

getProperty, getProperty, list, list, load, propertyNames, save, setProperty, store

Methods inherited from class java.util.Hashtable

clear, clone, contains, containsKey, containsValue, elements, entrySet, equals, get, hashCode, isEmpty, keys, keySet, put, putAll, rehash, remove, size, toString, values

Methods inherited from class java.lang.Object

finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

vitalKey

protected java.lang.String vitalKey

Holds the Vital Sign unique key these properties are for

VITALS_KEY_PROPERTY_PREFIX

protected static final java.lang.String VITALS_KEY_PROPERTY_PREFIX

Property prefix for all vital sign properties.

See Also:

Constant Field Values

IMPLEMENTATION_CLASS_NAME_PROPERTY

public static final java.lang.String IMPLEMENTATION_CLASS_NAME_PROPERTY

The name of the property to look up for the connectionInfoSourceClass name.

See Also:

Constant Field Values

IMPLEMENTATION_CLASS_NAME_DEFAULT

public static final java.lang.String IMPLEMENTATION_CLASS_NAME_DEFAULT

The default connectionInfoSourceClass name.

MEASUREMENT_CLASS_PROPERTY

public static final java.lang.String MEASUREMENT_CLASS_PROPERTY

The name of the property to look up for the measurement class for the vital sign.

See Also:

Constant Field Values

MEASUREMENT_CLASS_DEFAULT

public static final java.lang.String MEASUREMENT_CLASS_DEFAULT

The default measurement class for the vital sign.

See Also:

Constant Field Values

measurementClass

protected java.lang.Class measurementClass

Holds a cached Class object (to save on reflection overhead) that is the equivalent of the measurement class above.

VITAL_NAME_PROPERTY

public static final java.lang.String VITAL_NAME_PROPERTY

The name of the property to look up for the nice display name of the vital sign.

See Also:

Constant Field Values

MEASUREMENT_UNIT_PROPERTY

public static final java.lang.String MEASUREMENT_UNIT_PROPERTY

The name of the property to look up for the measure display name.

See Also:

Constant Field Values

MEASUREMENT_UNIT_DEFAULT

public static final java.lang.String MEASUREMENT_UNIT_DEFAULT

The default measure display name

See Also:

Constant Field Values

MEASUREMENT_FREQUENCY_PROPERTY

public static final java.lang.String MEASUREMENT_FREQUENCY_PROPERTY

The name of the property to look up for the measurement frequency.

See Also:

Constant Field Values

MEASUREMENT_FREQUENCY_DEFAULT

public static final long MEASUREMENT_FREQUENCY_DEFAULT

The default value for measurement frequency.

See Also:

Constant Field Values

REFRESH_INSTANCE_PROPERTY

public static final java.lang.String REFRESH_INSTANCE_PROPERTY

The name of the property to look up for the refresh instance frequency.

See Also:

Constant Field Values

REFRESH_INSTANCE_DEFAULT

public static final long REFRESH_INSTANCE_DEFAULT

Default value for the refresh instance property.

See Also:

Constant Field Values

MINIMUM_MEASUREMENTS_PROPERTY

public static final java.lang.String MINIMUM_MEASUREMENTS_PROPERTY

Property for minimum measurements taken before alerts logged.

See Also:

Constant Field Values

MINIMUM_MEASUREMENTS_DEFAULT

public static final long MINIMUM_MEASUREMENTS_DEFAULT

The default minimum number of measurements.

See Also:

Constant Field Values

NEW_HIGH_PROPERTY

public static final java.lang.String NEW_HIGH_PROPERTY

The name of the property to look up for the alertAtNewHigh setting.

See Also:

Constant Field Values

NEW_HIGH_DEFAULT

public static final boolean NEW_HIGH_DEFAULT

The default value of the alertAtNewHigh property

See Also:

Constant Field Values

ALERT_AT_AVERAGE_PROPERTY

public static final java.lang.String ALERT_AT_AVERAGE_PROPERTY

The name of the property to look up for the alertAtAveragePercentileExceeded property.

See Also:

Constant Field Values

ALERT_AT_AVERAGE_DEFAULT

public static final long ALERT_AT_AVERAGE_DEFAULT

The class name of the AbstractVitalMeasurement subclass to use to record measurements for the vital sign.

See Also:

Constant Field Values

ALERT_AT_MAX_PERCENT_PROPERTY

public static final java.lang.String ALERT_AT_MAX_PERCENT_PROPERTY

The name of the property to look up for the alert at max percentage property.

See Also:

Constant Field Values

ALERT_AT_MAX_PERCENT_DEFAULT

public static final long ALERT_AT_MAX_PERCENT_DEFAULT

The default value of the alert at max percentage property.

See Also:

Constant Field Values

MEASURMENT_HISTORY_PROPERTY

public static final java.lang.String MEASURMENT_HISTORY_PROPERTY

The name of the property to tell the size of the recently collected measurements queue.

See Also:

Constant Field Values

MEASURMENT_HISTORY_DEFAULT

public static final long MEASURMENT_HISTORY_DEFAULT

The class name of the AbstractVitalMeasurement subclass to use to record measurements for the vital sign.

See Also:

Constant Field Values

RECENT_ALERT_HISTORY_PROPERTY

public static final java.lang.String RECENT_ALERT_HISTORY_PROPERTY

The name of the property to look up for the alert history size

See Also:

Constant Field Values

RECENT_ALERT_HISTORY_DEFAULT

public static final long RECENT_ALERT_HISTORY_DEFAULT

The default alert history size

See Also:

Constant Field Values

ALERT_FREQUENCY_PROPERTY

public static final java.lang.String ALERT_FREQUENCY_PROPERTY

The name of the property to look up for the alert frequency

See Also:

Constant Field Values

ALERT_FREQUENCY_DEFAULT

public static final long ALERT_FREQUENCY_DEFAULT

The default value of alert frequency, at a maximum, alert every 5 minutes.

See Also:

Constant Field Values

LOGGING_FREQUENCY_PROPERTY

public static final java.lang.String LOGGING_FREQUENCY_PROPERTY

The name of the property to look up for the logging frequency

See Also:

Constant Field Values

LOGGING_FREQUENCY_DEFAULT

public static final long LOGGING_FREQUENCY_DEFAULT

The default value for logging frequency, that is, no logs are generated by default.

See Also:

Constant Field Values

LOGGER_PROPERTY

public static final java.lang.String LOGGER_PROPERTY

The name of the property to look up for the JDK logger.

See Also:

Constant Field Values

LOGGER_DEFAULT

public static final java.lang.String LOGGER_DEFAULT

The default JDK logger VitalsLogger.

See Also:

Constant Field Values

Constructor Detail

VitalSignProperties

public VitalSignProperties(java.lang.String vitalKey,
                           java.util.Properties properties)

Passthrough constructor for dynamic properties (that is, properties which DON'T come from property files). Use this constructor to create dynamic Vital Sign properties, and use the getInstance() factory method above to create vital sign properties from property file entries.

Method Detail

getInstance

public static VitalSignProperties getInstance(java.lang.String vitalKey)

Factory method to retrieve a set of properties for the named vital sign. This method currently only looks in the main property file for vital sign properties.

getPeriodicVitalKeys

public static java.util.Collection getPeriodicVitalKeys()

Helper method to look through all the properties in the property file and return the vitalKeys of anything that should be loaded for periodic collection.

getImplementationClassName

public java.lang.String getImplementationClassName()

Returns the name of the class that implements the vital sign.

basicGetMeasurementClass

protected java.lang.Class basicGetMeasurementClass()

Helper method to return a measurement class

getMeasurementClass

public java.lang.Class getMeasurementClass()

Returns the class that should be used to hold measurements for the vital sign.

getVitalName

public java.lang.String getVitalName()

Returns the nice display name of the vital sign. If none given, returns the vitalKey.

getMeasurementUnit

public java.lang.String getMeasurementUnit()

Returns the display name for the measure collected by the vital sign (for example, milliseconds elapsed, requests per second).

getMeasurementFrequencyInSeconds

public long getMeasurementFrequencyInSeconds()

Returns how often the vitals manager must collect a measurement on this vital sign. If this value is zero, the vital sign is not collected automatically (you must programmatically do the collection yourself). If this value is non-zero, then the vitals sampling thread kicks in every second, looks through any registered vital signs with a non-zero measurement frequency, checks the last time it was collected, and if not collected recently, asks that vital sign for a current measurement.

shouldMeasureVitalSignPeriocially

public boolean shouldMeasureVitalSignPeriocially()

Returns if the vital sign should be measured periodically (basically if measurement frequence greater than zero, then yes).

getRefreshChildInstanceListInSeconds

public long getRefreshChildInstanceListInSeconds()

Returns how often a vital sign with child instances needs to see if new instances need to be created.

getAlertAfterMinimumMeasurementsTaken

public long getAlertAfterMinimumMeasurementsTaken()

Returns the minimum measurements taken before alerts logged. If this property is zero, no alerts will ever be logged.

alertAtNewHigh

public boolean alertAtNewHigh()

Returns the setting to see if an alert should be generated if a newly recorded measure is the high measure.

getAlertAtAveragePercentileExceeded

public long getAlertAtAveragePercentileExceeded()

Returns the percentage of average that, if exceeded, an alert will be generated.

getAlertAtMaximumAvailablePercentileExceeded

public long getAlertAtMaximumAvailablePercentileExceeded()

Returns the percentage that if a newly recorded measurement exceeds this percentage of the theoritical max for the vital sign, an alert will be generated.

getRecentMeasurementHistorySize

public long getRecentMeasurementHistorySize()

Returns the length of the queue keeping the most recent measurements. If this value is zero, no history is kept.

getRecentAlertHistorySize

public long getRecentAlertHistorySize()

Returns the number of alerts generated that should be kept in memory as a history. If this value is zero, no alert history should be kept.

getAlertFrequencyInSeconds

public long getAlertFrequencyInSeconds()

Returns the minimum time in seconds that can elapse between alerts getting logged. This setting is very important so that we don't flood the logs with too many alerts.

getLoggingFrequencyInSeconds

public long getLoggingFrequencyInSeconds()

Returns the number of seconds between logging the currently recorded value of a captured vital sign measurement. If this value is zero, no vital sign measurements will be logged.

getLoggerName

public java.lang.String getLoggerName()

Returns the JDK logger that will be used when logging measurements and alerts.