net.i2p.stat

## Class Rate

- java.lang.Object
- - net.i2p.stat.Rate

-     public class Rate
      extends Object

  Simple rate calculator for periodically sampled data points - determining an average value over a period, the number of events in that period, the maximum number of events (using the interval between events), and lifetime data. If value is always a constant, you should be using Frequency instead.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `Rate(long period)` A rate with period shorter than Router.COALESCE_TIME = 50*1000 has to be manually coalesced before values are fetched from it.
    `Rate(Properties props, String prefix, boolean treatAsCurrent)` Create a new rate and load its state from the properties, taking data from the data points underneath the given prefix.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addData(long value)` Accrue the data in current period as an instantaneous event.
    `void` | `addData(long value, long eventDuration)` Accrue the data in current period as if the event took the specified amount of time If value is always a constant, you should be using Frequency instead.
    `void` | `coalesce()`
    `RateAverages` | `computeAverages()` Computes the averages for this rate.
    `RateAverages` | `computeAverages(RateAverages out, boolean useLifetime)` Computes the averages and stores them in the provided object.
    `boolean` | `equals(Object obj)` This is used in GraphGenerator and GraphListener.
    `double` | `getAverageValue()` What was the average value across the events in the last period?
    `double` | `getAvgOrLifetimeAvg()` Gets the average value, or the lifetime average if no recent data.
    `long` | `getCreationDate()` when was this rate created?
    `long` | `getCurrentEventCount()` in current (partial) period, how many events have occurred?
    `long` | `getCurrentTotalEventTime()` in current (partial) period, how much of the time has been spent doing the events?
    `double` | `getCurrentTotalValue()` in current (partial) period, what is the total value acrued through all events?
    `double` | `getExtremeAverageValue()` During the extreme period (i.e.
    `long` | `getExtremeEventCount()` when the max(totalValue) was achieved, how many events occurred in that period? Note that this is not necesarily the highest event count; that isn't tracked.
    `double` | `getExtremeEventSaturation()` During the extreme period (i.e.
    `double` | `getExtremeSaturationLimit()` During the extreme period (i.e.
    `long` | `getExtremeTotalEventTime()` when the max(totalValue) was achieved, how much of the time was spent doing the events?
    `double` | `getExtremeTotalValue()` what was the max total value acrued in any period?
    `long` | `getLastCoalesceDate()` when was the rate last coalesced?
    `long` | `getLastEventCount()` in the last full period, how many events occurred?
    `double` | `getLastEventSaturation()` During the last period, how much of the time was spent actually processing events in proportion to how many events could have occurred if there were no intervals?
    `double` | `getLastSaturationLimit()` using the last period's rate, what is the total value that could have been sent if events were constant?
    `long` | `getLastTotalEventTime()` in the last full period, how much of the time was spent doing the events?
    `double` | `getLastTotalValue()` in the last full period, what was the total value acrued through all events?
    `double` | `getLifetimeAverageValue()` What was the average value across the events since the stat was created?
    `long` | `getLifetimeEventCount()` since rate creation, how many events have occurred?
    `double` | `getLifetimeEventSaturation()` During the lifetime of this stat, how much of the time was spent actually processing events in proportion to how many events could have occurred if there were no intervals?
    `long` | `getLifetimePeriods()` how many periods have we already completed?
    `long` | `getLifetimeTotalEventTime()` since rate creation, how much of the time was spent doing the events?
    `double` | `getLifetimeTotalValue()` since rate creation, what was the total value acrued through all events?
    `double` | `getPercentageOfExtremeValue()` What was the total value, compared to the total value in the extreme period (i.e.
    `double` | `getPercentageOfLifetimeValue()` How large was the last period's value as compared to the lifetime average value? Warning- returns ratio, not percentage (i.e.
    `long` | `getPeriod()` how large should this rate's cycle be?
    `RateStat` | `getRateStat()`
    `RateSummaryListener` | `getSummaryListener()`
    `int` | `hashCode()` It doesn't appear that Rates are ever stored in a Set or Map (RateStat stores in an array) so let's make this easy.
    `void` | `load(Properties props, String prefix, boolean treatAsCurrent)` Load this rate from the properties, taking data from the data points underneath the given prefix.
    `void` | `setRateStat(RateStat rs)`
    `void` | `setSummaryListener(RateSummaryListener listener)`
    `void` | `store(String prefix, StringBuilder buf)` Stores the rate data to a string builder.
    `void` | `store(String prefix, StringBuilder buf, boolean addComments)` Stores the rate data to a string builder.
    `String` | `toString()`

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### Rate

          public Rate(long period)
               throws IllegalArgumentException

      A rate with period shorter than Router.COALESCE_TIME = 50*1000 has to be manually coalesced before values are fetched from it.
      Parameters:
        `period` - number of milliseconds in the period this rate deals with, min 1, max Integer.MAX_VALUE
      Throws:
        `IllegalArgumentException` - if the period is invalid

    - #### Rate

          public Rate(Properties props,
                      String prefix,
                      boolean treatAsCurrent)
               throws IllegalArgumentException

      Create a new rate and load its state from the properties, taking data from the data points underneath the given prefix.

      (e.g. prefix = "profile.dbIntroduction.60m", this will load the associated data points such as "profile.dbIntroduction.60m.lifetimeEventCount"). The data can be exported through store(outputStream, "profile.dbIntroduction.60m").

      Parameters:
        `prefix` - prefix to the property entries (should NOT end with a period)
        `treatAsCurrent` - if true, we'll treat the loaded data as if no time has elapsed since it was written out, but if it is false, we'll treat the data with as much freshness (or staleness) as appropriate.
      Throws:
        `IllegalArgumentException` - if the data was formatted incorrectly

  - ### Method Detail

    - #### addData

          public void addData(long value)

      Accrue the data in current period as an instantaneous event. If value is always a constant, you should be using Frequency instead. If you always use this call, eventDuration is always zero, and the various get*Saturation*() and get*EventTime() methods will return zero.

    - #### addData

          public void addData(long value,
                              long eventDuration)

      Accrue the data in current period as if the event took the specified amount of time If value is always a constant, you should be using Frequency instead. If eventDuration is nonzero, then the various get*Saturation*() and get*EventTime() methods will also return nonzero.

           There are at least 4 possible strategies for eventDuration:

             1) eventDuration is always zero.
                The various get*Saturation*() and get*EventTime() methods will return zero.

             2) Each eventDuration is relatively small, and reflects processing time.
                This is probably the original meaning of "saturation", as it allows you
                to track how much time is spent gathering the stats.
                get*EventTime() will be close to 0.
                get*EventSaturation() will return values close to 0,
                get*SaturationLimit() will return adjusted values for the totals.

             3) The total of the eventDurations are approximately equal to total elapsed time.
                get*EventTime() will be close to the period.
                get*EventSaturation() will return values close to 1,
                get*SaturationLimit() will return adjusted values for the totals.

             4) Each eventDuration is not a duration at all, but someother independent data.
                get*EventTime() may be used to retrieve the data.
                get*EventSaturation() are probably useless.
                get*SaturationLimit() are probably useless.

      Parameters:
        `value` - value to accrue in current period
        `eventDuration` - how long it took to accrue this data (set to 0 if it was instantaneous)

    - #### coalesce

          public void coalesce()

    - #### computeAverages

          public RateAverages computeAverages()

      Computes the averages for this rate.
      Returns:
        a thread-local temp object containing computed averages.

    - #### computeAverages

          public RateAverages computeAverages(RateAverages out,
                                              boolean useLifetime)

      Computes the averages and stores them in the provided object.
      Parameters:
        `out` - where to store the computed averages.
        `useLifetime` - whether the lifetime average should be used if there are no events.
      Returns:
        the same RateAverages object for chaining

    - #### equals

          public boolean equals(Object obj)

      This is used in GraphGenerator and GraphListener. We base it on the stat we are tracking, not the stored data.
      Overrides:
        `equals` in class `Object`

    - #### getAverageValue

          public double getAverageValue()

      What was the average value across the events in the last period?

    - #### getAvgOrLifetimeAvg

          public double getAvgOrLifetimeAvg()

      Gets the average value, or the lifetime average if no recent data.
      Returns:
        the average or lifetime average depending on last event count

    - #### getCreationDate

          public long getCreationDate()

      when was this rate created?

    - #### getCurrentEventCount

          public long getCurrentEventCount()

      in current (partial) period, how many events have occurred?

    - #### getCurrentTotalEventTime

          public long getCurrentTotalEventTime()

      in current (partial) period, how much of the time has been spent doing the events?

    - #### getCurrentTotalValue

          public double getCurrentTotalValue()

      in current (partial) period, what is the total value acrued through all events?

    - #### getExtremeAverageValue

          public double getExtremeAverageValue()

      During the extreme period (i.e. the period with the highest total value), what was the average value?

    - #### getExtremeEventCount

          public long getExtremeEventCount()

      when the max(totalValue) was achieved, how many events occurred in that period? Note that this is not necesarily the highest event count; that isn't tracked.

    - #### getExtremeEventSaturation

          public double getExtremeEventSaturation()

      During the extreme period (i.e. the period with the highest total value), how much of the time was spent actually processing events in proportion to how many events could have occurred if there were no intervals?
      Returns:
        ratio, or 0 if the statistic doesn't use event times

    - #### getExtremeSaturationLimit

          public double getExtremeSaturationLimit()

      During the extreme period (i.e. the period with the highest total value), what is the total value that could have been sent if events were constant?
      Returns:
        event total at saturation, or 0 if no event times are measured

    - #### getExtremeTotalEventTime

          public long getExtremeTotalEventTime()

      when the max(totalValue) was achieved, how much of the time was spent doing the events?

    - #### getExtremeTotalValue

          public double getExtremeTotalValue()

      what was the max total value acrued in any period?

    - #### getLastCoalesceDate

          public long getLastCoalesceDate()

      when was the rate last coalesced?

    - #### getLastEventCount

          public long getLastEventCount()

      in the last full period, how many events occurred?

    - #### getLastEventSaturation

          public double getLastEventSaturation()

      During the last period, how much of the time was spent actually processing events in proportion to how many events could have occurred if there were no intervals?
      Returns:
        ratio, or 0 if event times aren't used

    - #### getLastSaturationLimit

          public double getLastSaturationLimit()

      using the last period's rate, what is the total value that could have been sent if events were constant?
      Returns:
        max total value, or 0 if event times aren't used

    - #### getLastTotalEventTime

          public long getLastTotalEventTime()

      in the last full period, how much of the time was spent doing the events?

    - #### getLastTotalValue

          public double getLastTotalValue()

      in the last full period, what was the total value acrued through all events?

    - #### getLifetimeAverageValue

          public double getLifetimeAverageValue()

      What was the average value across the events since the stat was created?

    - #### getLifetimeEventCount

          public long getLifetimeEventCount()

      since rate creation, how many events have occurred?

    - #### getLifetimeEventSaturation

          public double getLifetimeEventSaturation()

      During the lifetime of this stat, how much of the time was spent actually processing events in proportion to how many events could have occurred if there were no intervals?
      Returns:
        ratio, or 0 if event times aren't used

    - #### getLifetimePeriods

          public long getLifetimePeriods()

      how many periods have we already completed?

    - #### getLifetimeTotalEventTime

          public long getLifetimeTotalEventTime()

      since rate creation, how much of the time was spent doing the events?

    - #### getLifetimeTotalValue

          public double getLifetimeTotalValue()

      since rate creation, what was the total value acrued through all events?

    - #### getPercentageOfExtremeValue

          public double getPercentageOfExtremeValue()

      What was the total value, compared to the total value in the extreme period (i.e. the period with the highest total value), Warning- returns ratio, not percentage (i.e. it is not multiplied by 100 here)

    - #### getPercentageOfLifetimeValue

          public double getPercentageOfLifetimeValue()

      How large was the last period's value as compared to the lifetime average value? Warning- returns ratio, not percentage (i.e. it is not multiplied by 100 here)

    - #### getPeriod

          public long getPeriod()

      how large should this rate's cycle be?

    - #### getRateStat

          public RateStat getRateStat()

    - #### getSummaryListener

          public RateSummaryListener getSummaryListener()

    - #### hashCode

          public int hashCode()

      It doesn't appear that Rates are ever stored in a Set or Map (RateStat stores in an array) so let's make this easy.
      Overrides:
        `hashCode` in class `Object`

    - #### load

          public void load(Properties props,
                           String prefix,
                           boolean treatAsCurrent)
                    throws IllegalArgumentException

      Load this rate from the properties, taking data from the data points underneath the given prefix.
      Parameters:
        `prefix` - prefix to the property entries (should NOT end with a period)
        `treatAsCurrent` - if true, we'll treat the loaded data as if no time has elapsed since it was written out, but if it is false, we'll treat the data with as much freshness (or staleness) as appropriate.
      Throws:
        `IllegalArgumentException` - if the data was formatted incorrectly

    - #### setRateStat

          public void setRateStat(RateStat rs)

    - #### setSummaryListener

          public void setSummaryListener(RateSummaryListener listener)

    - #### store

          public void store(String prefix,
                            StringBuilder buf)
                     throws IOException

      Stores the rate data to a string builder. Includes comment lines
      Throws:
        `IOException`

    - #### store

          public void store(String prefix,
                            StringBuilder buf,
                            boolean addComments)
                     throws IOException

      Stores the rate data to a string builder.
      Parameters:
        `addComments` - add comment lines to the output
      Throws:
        `IOException`

    - #### toString

          public String toString()

      Overrides:
        `toString` in class `Object`