G
- The aggregation entity group class. Note that the entity group will be used as a key to HashMaps,
so it must have a valid Object.hashCode()
and Object.equals(Object)
implementation.E
- The entity class. Note that the entity will be used as a key to HashMaps, so it must have
a valid Object.hashCode()
and Object.equals(Object)
implementation.public class MetricSampleAggregator<G,E extends Entity<G>> extends LongGenerationed
MetricSamples
for entities
. It uses
a cyclic buffer to keep track of the most recent N (configured) windows. The oldest windows are evicted when
the buffer is full.
The MetricSampleAggregator
aggregates the metrics of each entities in each window. The aggregation
can be viewed as two dimensions: per entity and per window.
From per entity's perspective, each entity would have sufficient metrics from all the windows when everything
works fine. However, it is also possible that some metrics may be missing from the MetricSampleAggregator
in one or more windows. If that happens, some Extrapolation
will be used to fill in the missing data.
If none of the Extrapolation
works. We claim the entity is invalid in this window. With above,
a given entity may have the following three states in any given window from the MetricSampleAggregator
's
perspective:
Furthermore, each entity belongs to an aggregation entity group. The aggregation entity group is only used
for metric aggregation purpose. Users can specify the AggregationOptions.Granularity
of the metric aggregation. The
granularity could be one of the following:
AggregationOptions.Granularity.ENTITY
: The validity of the entities in the same aggregation group
are considered independently, i.e. an invalid entity in an aggregation group does not invalidate the other
entities in the same aggregation entity group.
AggregationOptions.Granularity.ENTITY_GROUP
: The validity of the entities in the same aggregation entity group are
considered as an entirety. i.e. a single invalid entity in the aggregation entity group invalidates all
the entities in the same aggregation entity group.
From per window's perspective, for each window, there is a given set of valid entities and entity
groups as described above. The validity of a window depends on the requirements specified in the
AggregationOptions
during the aggregation. More specifically whether the entity coverage (valid entity
ratio) and entity group coverage (valid entity group ratio) meet the requirements.
This class is thread safe.
Modifier and Type | Class and Description |
---|---|
protected static class |
MetricSampleAggregator.SampleType
The
MetricSamples type which the aggregator collects. |
Modifier and Type | Field and Description |
---|---|
protected ConcurrentMap<E,E> |
identityEntityMap |
protected MetricDef |
metricDef |
protected byte |
minSamplesPerWindow |
protected long |
monitoringPeriodMs |
protected int |
numWindows |
protected int |
numWindowsToKeep |
protected MetricSampleAggregator.SampleType |
sampleType |
protected long |
windowMs |
generation
Constructor and Description |
---|
MetricSampleAggregator(int numWindows,
long windowMs,
byte minSamplesPerWindow,
int completenessCacheSize,
MetricDef metricDef)
Construct the metric sample aggregator.
|
Modifier and Type | Method and Description |
---|---|
boolean |
addSample(MetricSample<G,E> sample)
Add a sample to the metric aggregator.
|
MetricSampleAggregationResult<G,E> |
aggregate(long from,
long to,
AggregationOptions<G,E> options)
Aggregate the metric samples in the given period into a
MetricSampleAggregationResult based on the
specified AggregationOptions . |
List<Long> |
allWindows() |
List<Long> |
availableWindows()
Get a list of available windows in the MetricSampleAggregator.
|
void |
clear()
Clear the MetricSampleAggregator.
|
MetricSampleCompleteness<G,E> |
completeness(long from,
long to,
AggregationOptions<G,E> options)
Get the
MetricSampleCompleteness of the MetricSampleAggregator with the given AggregationOptions
for a given period of time. |
Long |
earliestWindow() |
long |
monitoringPeriodMs()
Get the length of time aggregator keeps samples in memory.
|
int |
numAvailableWindows()
Get the number of available windows in the MetricSampleAggregator.
|
int |
numAvailableWindows(long from,
long to)
Get the number of available windows in the given time range, excluding the current active window.
|
int |
numSamples()
Get the total number of samples that is currently aggregated by the MetricSampleAggregator.
|
Map<E,ValuesAndExtrapolations> |
peekCurrentWindow()
Peek the information for all the available entities of the current window.
|
void |
removeEntities(Set<E> entities)
Remove the given set of entities from the MetricSampleAggregator.
|
void |
removeEntityGroup(Set<G> entityGroups)
Remove the given set of entity groups from the MetricSampleAggregator.
|
void |
retainEntities(Set<E> entities)
Keep the given set of entities in the MetricSampleAggregator and remove the rest of the entities.
|
void |
retainEntityGroup(Set<G> entityGroups)
Keep the given set of entity groups in the MetricSampleAggregator and remove the reset of the entity groups.
|
compareGeneration, compareGeneration, generation, setGeneration
protected final ConcurrentMap<E extends Entity<G>,E extends Entity<G>> identityEntityMap
protected final int numWindows
protected final byte minSamplesPerWindow
protected final int numWindowsToKeep
protected final long windowMs
protected final long monitoringPeriodMs
protected final MetricDef metricDef
protected MetricSampleAggregator.SampleType sampleType
public MetricSampleAggregator(int numWindows, long windowMs, byte minSamplesPerWindow, int completenessCacheSize, MetricDef metricDef)
numWindows
- the number of windows needed.windowMs
- the size of each window in millisecondsminSamplesPerWindow
- minimum samples per window.completenessCacheSize
- the completeness cache size, i.e. the number of recent completeness query result to
cache.metricDef
- metric definitions.public boolean addSample(MetricSample<G,E> sample)
sample
- The metric sample to add.public MetricSampleAggregationResult<G,E> aggregate(long from, long to, AggregationOptions<G,E> options) throws NotEnoughValidWindowsException
MetricSampleAggregationResult
based on the
specified AggregationOptions
.
The aggregation result contains all the entities in AggregationOptions.interestedEntities()
.
For the entities that are completely missing, an empty result is added with all the value set to 0.0 and
all the window indices marked as Extrapolation.NO_VALID_EXTRAPOLATION
.
from
- the starting timestamp of the aggregation period in milliseconds.to
- the end timestamp of the aggregation period in milliseconds.options
- the AggregationOptions
used to perform the aggregation.MetricSampleAggregationResult
based on the given AggregationOptions.NotEnoughValidWindowsException
public Map<E,ValuesAndExtrapolations> peekCurrentWindow()
public MetricSampleCompleteness<G,E> completeness(long from, long to, AggregationOptions<G,E> options)
MetricSampleCompleteness
of the MetricSampleAggregator with the given AggregationOptions
for a given period of time. The current active window is excluded.from
- starting time of the period to check.to
- ending time of the period to check.options
- the AggregationOptions
to use for the completeness check.MetricSampleCompleteness
of the MetricSampleAggregator.public List<Long> availableWindows()
public int numAvailableWindows()
public int numAvailableWindows(long from, long to)
from
- the starting time of the time range. (inclusive)to
- the end time of the time range. (inclusive)public List<Long> allWindows()
public Long earliestWindow()
public int numSamples()
public void retainEntities(Set<E> entities)
entities
- the entities to retain.public void removeEntities(Set<E> entities)
entities
- the entities to remove.public void retainEntityGroup(Set<G> entityGroups)
entityGroups
- the entity groups to retain.public void removeEntityGroup(Set<G> entityGroups)
entityGroups
- the entity groups to remove from the MetricSampleAggregator.public void clear()
public long monitoringPeriodMs()