java.lang.Object
net.i2p.stat.RateStat
public class RateStatextends Object
Coordinates a moving rate over various periods.

  • Field Details

    • _statName

      private final String _statName
      Unique name of the statistic.

    • _groupName

      private final String _groupName
      Grouping under which the stat is kept.

    • _description

      private final String _description
      Describes the stat.

    • _rates

      protected final Rate[] _rates
      Actual rate objects for this statistic.

    • _coalesceFailures

      private final AtomicLong _coalesceFailures
      How many per-rate Rate.coalesce() calls have thrown. A rate that throws is skipped, never propagated: see coalesceStats().

    • _firstFailurePeriod

      private volatile String _firstFailurePeriod
      Identity of the first rate that failed to coalesce, and its cause, so the log names which period of which stat is broken instead of only counting.

    • _firstFailureCause

      private volatile Throwable _firstFailureCause
      What first failed to write the stats file.

    • NL

      private static final String NL
      Line separator of the report file.

    • HR

      private static final String HR
      Rule drawn between report sections
      See Also:

  • Constructor Details

    • RateStat

      public RateStat(String name, String description, String group, long[] periods)
      Unique name of the statistic.
      Parameters:
      name - unique name of the statistic
      description - simple description of the statistic
      group - used to group statistics together
      periods - array of period lengths (in milliseconds), must not be empty
      Throws:
      IllegalArgumentException - if periods is empty

    • RateStat

      RateStat(String name, String description, String group, Rate[] rates)
      Constructor taking pre-built rates, for tests that need a rate which throws.

      The public constructor cannot express this because it always builds working rates, and a Rate cannot be made to fail without a fault injected into it. The isolation in coalesceStats() is only worth anything if it can be shown to hold when a rate really does throw.

      Parameters:
      name - unique name of the statistic
      description - simple description of the statistic
      group - used to group statistics together
      rates - the rates to coalesce, must not be empty
      Throws:
      IllegalArgumentException - if rates is empty

  • Method Details

    • setSampleDelivery

      void setSampleDelivery(RateSampleDelivery delivery)
      Route coalesced samples for every rate in this stat through delivery instead of calling the summary listener inline.

      Set by StatManager immediately after construction. A setter rather than a constructor argument so the public constructor signature — and its callers — are unaffected.

      Parameters:
      delivery - the shared delivery queue, or null for inline delivery

    • getCoalesceSkips

      long getCoalesceSkips()
      Sum of the per-rate coalesce skip counts; see Rate.getCoalesceSkips().
      Returns:
      total coalesce skips across this stat's rates

    • getCoalesceCount

      public long getCoalesceCount()
      Sum of the per-rate successful coalesce counts; see Rate.getCoalesceCount().
      Returns:
      total coalesces across this stat's rates

    • getCoalesceBacklogCollapses

      long getCoalesceBacklogCollapses()
      Sum of the per-rate backlog collapse counts; see Rate.getCoalesceBacklogCollapses().
      Returns:
      total backlog collapses across this stat's rates

    • getRecentSamples

      public List<Rate.CoalescedSample> getRecentSamples(int max)
      Retained coalesced samples for backfill, oldest first.

      Read from the shortest-period rate (_rates[0], periods being held in ascending order) because that is the rate whose steps its RRD stores, and therefore the one a listener writing history has to replay.

      Parameters:
      max - the most samples to return, clamped by the rate's ring
      Returns:
      an immutable list of at most max samples, oldest first, never null

    • addData

      public void addData(long value, long eventDuration)
      Update all of the rates for the various periods with the given value.
      Parameters:
      value - the sample value added to every period's rate
      eventDuration - the event duration

    • addData

      public void addData(long value)
      Update all of the rates for the various periods with the given value. Zero duration.
      Parameters:
      value - the sample value added to every period's rate

    • coalesceStats

      public void coalesceStats()
      Coalesce every period's rate, isolating each one.

      A rate that throws must not stop its siblings. StatManager walks every stat in one pass on the coalesce timer, so an exception escaping here would abandon every stat later in that pass: their rates would silently stop coalescing, their listeners would stop receiving samples, and their graphs would freeze with nothing logged anywhere - which is exactly the failure this method exists to make impossible.

      The first failure is remembered with the period that produced it, so StatManager can name the offending stat rather than only counting anonymous failures.

    • getCoalesceFailures

      long getCoalesceFailures()
      Number of per-rate coalesce calls that have thrown since construction.
      Returns:
      the running failure count

    • getFirstCoalesceFailurePeriod

      String getFirstCoalesceFailurePeriod()
      The period of the first rate that failed to coalesce, or null if none has.
      Returns:
      the failing rate's period in ms, or null

    • getFirstCoalesceFailureCause

      Throwable getFirstCoalesceFailureCause()
      The cause of the first coalesce failure, for the log line.
      Returns:
      the first failure's throwable, or null

    • getName

      public String getName()
      Unique name for this rate stat.
      Returns:
      the unique name of this statistic

    • getGroupName

      public String getGroupName()
      Grouping name for this rate stat.
      Returns:
      the grouping name under which this statistic is kept

    • getDescription

      public String getDescription()
      Description of what this rate stat measures.
      Returns:
      a simple description of this statistic

    • getPeriods

      public long[] getPeriods()
      Tracked periods for this rate.
      Returns:
      the periods this rate is tracked over, in milliseconds

    • getLifetimeAverageValue

      public double getLifetimeAverageValue()
      Lifetime average from the shortest period.
      Returns:
      the lifetime average value from the shortest period's rate

    • getLifetimeEventCount

      public long getLifetimeEventCount()
      Lifetime event count from the shortest period.
      Returns:
      the lifetime event count from the shortest period's rate

    • getRate

      public Rate getRate(long period)
      Returns rate with requested period if it exists, otherwise null.
      Parameters:
      period - the rate period, in milliseconds
      Returns:
      the Rate whose period equals this one exactly, or null

    • containsRate

      public boolean containsRate(long period)
      Tests if a rate with the provided period exists within this RateStat.
      Parameters:
      period - the rate period, in milliseconds
      Returns:
      true if exists

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object

    • equals

      public boolean equals(Object obj)
      Object to compare.
      Overrides:
      equals in class Object
      Parameters:
      obj - the object to compare
      Returns:
      true if equal by name, group, description, and rates

    • nameGroupDescEquals

      boolean nameGroupDescEquals(RateStat rs)
      Whether the other stat shares name, group, and description.
      Parameters:
      rs - the other RateStat
      Returns:
      true if both stats carry the same group name, description and stat name

    • store

      public void store(OutputStream out, String prefix) throws IOException
      Includes comment lines.
      Parameters:
      out - the output stream
      prefix - the property prefix
      Throws:
      IOException - if an I/O error occurs

    • store

      public void store(OutputStream out, String prefix, boolean addComments) throws IOException
      Stores the rate statistics to an output stream.
      Parameters:
      out - the output stream
      prefix - the property prefix
      addComments - add comment lines to the output
      Throws:
      IOException - if an I/O error occurs

    • load

      public void load(Properties props, String prefix, boolean treatAsCurrent) throws IllegalArgumentException
      Load this rate stat from the properties, populating all of the rates contained underneath it. The comes from the given prefix (e.g. if we are given the prefix "profile.dbIntroduction", a series of rates may be found underneath "profile.dbIntroduction.60s", "profile.dbIntroduction.60m", and "profile.dbIntroduction.24h"). This RateStat must already be created, with the specified rate entries constructed - this merely loads them with data.
      Parameters:
      props - the properties holding the prefixed rate entries to read
      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