org.apache.geode.Statistics Maven / Gradle / Ivy
Show all versions of geode-core Show documentation
/*
* Licensed to the Apache Software Foundation (ASF) under one or more contributor license
* agreements. See the NOTICE file distributed with this work for additional information regarding
* copyright ownership. The ASF licenses this file to You under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance with the License. You may obtain a
* copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software distributed under the License
* is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
* or implied. See the License for the specific language governing permissions and limitations under
* the License.
*/
package org.apache.geode;
import java.util.function.DoubleSupplier;
import java.util.function.IntSupplier;
import java.util.function.LongSupplier;
/**
* Instances of this interface maintain the values of various application-defined statistics. The
* statistics themselves are described by an instance of {@link StatisticsType}.
*
*
* To get an instance of this interface use an instance of {@link StatisticsFactory}.
*
*
* For improved performance, each statistic may be referred to by its {@link #nameToDescriptor
* descriptor}.
*
* For optimal performance, each statistic may be referred to by its {@link #nameToId id} in the
* statistics object. Note that ids can not be mapped back to their name and methods that take ids
* are unsafe. It is important to call the correct type of method for the given id. For example if
* your stat is a long then incLong must be called instead of incDouble.
*
* Note that as of the 5.1 release the incLong, and
* incDouble methods no longer return the new value of the statistic. They now return
* void. This incompatible change was made to allow for a more efficient concurrent
* increment implementation.
*
*
* @see Package introduction
*
*
* @since GemFire 3.0
*
*/
public interface Statistics {
/**
* Closes these statistics. After statistics have been closed, they are no longer archived. A
* value access on a closed statistics always results in zero. A value modification on a closed
* statistics is ignored.
*/
void close();
//////////////////////// accessor Methods ///////////////////////
/**
* Returns the id of the statistic with the given name in this statistics instance.
*
* @param name the name of the statistic
* @return the id of the statistic
* @throws IllegalArgumentException No statistic named name exists in this statistics
* instance.
*
* @see StatisticsType#nameToId
*/
int nameToId(String name);
/**
* Returns the descriptor of the statistic with the given name in this statistics instance.
*
* @param name the name of the statistic
* @return the {@link StatisticDescriptor descriptor} of the statistic
* @throws IllegalArgumentException No statistic named name exists in this statistics
* instance.
*
* @see StatisticsType#nameToDescriptor
*/
StatisticDescriptor nameToDescriptor(String name);
/**
* Gets a value that uniquely identifies this statistics.
*
* @return a value that uniquely identifies this statistics
*/
long getUniqueId();
/**
* Gets the {@link StatisticsType} of this instance.
*
* @return the {@link StatisticsType} of this instance
*/
StatisticsType getType();
/**
* Gets the text associated with this instance that helps identify it.
*
* @return the text associated with this instance that helps identify it
*/
String getTextId();
/**
* Gets the number associated with this instance that helps identify it.
*
* @return the number associated with this instance that helps identify it
*/
long getNumericId();
/**
* Returns true if modifications are atomic. This means that multiple threads, can safely modify
* this instance without extra synchronization.
*
* Returns false if modifications are not atomic. This means that modifications to this instance
* are cheaper but not thread safe.
*
* @return whether modifications are atomic
*/
boolean isAtomic();
/**
* Returns true if the instance has been {@link #close closed}.
*
* @return whether the instance has been {@link #close closed}.
*/
boolean isClosed();
//////////////////////// set() Methods ///////////////////////
/**
* Sets the value of a statistic with the given id whose type is int.
*
* @param id a statistic id obtained with {@link #nameToId} or {@link StatisticsType#nameToId}.
* @param value the value to set the statistic to
*
* @throws ArrayIndexOutOfBoundsException If the id is invalid.
* @deprecated as of Geode 1.10, use {@link #setLong(int, long)} instead
*/
@Deprecated
void setInt(int id, int value);
/**
* Sets the value of a named statistic of type int
*
* @param name the name of the statistic
* @param value the value to set the statistic to
* @throws IllegalArgumentException If no statistic exists named name or if the
* statistic with name name is not of type int.
* @deprecated as of Geode 1.10, use {@link #setLong(String, long)} instead
*/
@Deprecated
void setInt(String name, int value);
/**
* Sets the value of a described statistic of type int
*
* @param descriptor a statistic descriptor obtained with {@link #nameToDescriptor} or
* {@link StatisticsType#nameToDescriptor}.
* @param value the value to set the statistic to
* @throws IllegalArgumentException If no statistic exists for the given descriptor
* or if the described statistic is not of type int.
* @deprecated as of Geode 1.10, use {@link #setLong(StatisticDescriptor, long)} instead
*/
@Deprecated
void setInt(StatisticDescriptor descriptor, int value);
/**
* Sets the value of a statistic with the given id whose type is long.
*
* @param id a statistic id obtained with {@link #nameToId} or {@link StatisticsType#nameToId}.
* @param value the value to set the statistic to
*
* @throws ArrayIndexOutOfBoundsException If the id is invalid.
*/
void setLong(int id, long value);
/**
* Sets the value of a described statistic of type long
*
* @param descriptor a statistic descriptor obtained with {@link #nameToDescriptor} or
* {@link StatisticsType#nameToDescriptor}.
* @param value the value to set the statistic to
* @throws IllegalArgumentException If no statistic exists for the given descriptor
* or if the described statistic is not of type long.
*/
void setLong(StatisticDescriptor descriptor, long value);
/**
* Sets the value of a named statistic of type long.
*
* @param name the name of the statistic
* @param value the value to set the statistic to
* @throws IllegalArgumentException If no statistic exists named name or if the
* statistic with name name is not of type long.
*/
void setLong(String name, long value);
/**
* Sets the value of a statistic with the given id whose type is double.
*
* @param id a statistic id obtained with {@link #nameToId} or {@link StatisticsType#nameToId}.
* @param value the value to set the statistic to
*
* @throws ArrayIndexOutOfBoundsException If the id is invalid.
*/
void setDouble(int id, double value);
/**
* Sets the value of a described statistic of type double
*
* @param descriptor a statistic descriptor obtained with {@link #nameToDescriptor} or
* {@link StatisticsType#nameToDescriptor}.
* @param value the value to set the statistic to
* @throws IllegalArgumentException If no statistic exists for the given descriptor
* or if the described statistic is not of type double.
*/
void setDouble(StatisticDescriptor descriptor, double value);
/**
* Sets the value of a named statistic of type double.
*
* @param name the name of the statistic
* @param value the value to set the statistic to
* @throws IllegalArgumentException If no statistic exists named name or if the
* statistic with name name is not of type double.
*/
void setDouble(String name, double value);
/////////////////////// get() Methods ///////////////////////
/**
* Returns the value of the identified statistic of type int.
*
* @param id a statistic id obtained with {@link #nameToId} or {@link StatisticsType#nameToId}.
* @return the value of the statistic
* @throws ArrayIndexOutOfBoundsException If the id is invalid.
* @deprecated as of Geode 1.10, use {@link #getLong(int)} instead
*/
@Deprecated
int getInt(int id);
/**
* Returns the value of the described statistic of type int.
*
* @param descriptor a statistic descriptor obtained with {@link #nameToDescriptor} or
* {@link StatisticsType#nameToDescriptor}.
* @return the value of the statistic
* @throws IllegalArgumentException If no statistic exists with the specified
* descriptor or if the described statistic is not of type int.
* @deprecated as of Geode 1.10, use {@link #getLong(StatisticDescriptor)} instead
*/
@Deprecated
int getInt(StatisticDescriptor descriptor);
/**
* Returns the value of the statistic of type int at the given name.
*
* @param name the name of the statistic
* @return the value of the statistic
* @throws IllegalArgumentException If no statistic exists with name name or if the
* statistic named name is not of type int.
* @deprecated as of Geode 1.10, use {@link #getLong(String)} instead
*/
@Deprecated
int getInt(String name);
/**
* Returns the value of the identified statistic of type long.
*
* @param id a statistic id obtained with {@link #nameToId} or {@link StatisticsType#nameToId}.
* @return the value of the statistic
* @throws ArrayIndexOutOfBoundsException If the id is invalid.
*/
long getLong(int id);
/**
* Returns the value of the described statistic of type long.
*
* @param descriptor a statistic descriptor obtained with {@link #nameToDescriptor} or
* {@link StatisticsType#nameToDescriptor}.
* @return the value of the statistic
* @throws IllegalArgumentException If no statistic exists with the specified
* descriptor or if the described statistic is not of type long.
*/
long getLong(StatisticDescriptor descriptor);
/**
* Returns the value of the statistic of type long at the given name.
*
* @param name the name of the statistic
* @return the value of the statistic
* @throws IllegalArgumentException If no statistic exists with name name or if the
* statistic named name is not of type long.
*/
long getLong(String name);
/**
* Returns the value of the identified statistic of type double.
*
* @param id a statistic id obtained with {@link #nameToId} or {@link StatisticsType#nameToId}.
* @return the value of the statistic
* @throws ArrayIndexOutOfBoundsException If the id is invalid.
*/
double getDouble(int id);
/**
* Returns the value of the described statistic of type double.
*
* @param descriptor a statistic descriptor obtained with {@link #nameToDescriptor} or
* {@link StatisticsType#nameToDescriptor}.
* @return the value of the statistic
* @throws IllegalArgumentException If no statistic exists with the specified
* descriptor or if the described statistic is not of type
* double.
*/
double getDouble(StatisticDescriptor descriptor);
/**
* Returns the value of the statistic of type double at the given name.
*
* @param name the name of the statistic
* @return the value of the statistic
* @throws IllegalArgumentException If no statistic exists with name name or if the
* statistic named name is not of type double.
*/
double getDouble(String name);
/**
* Returns the value of the identified statistic.
*
* @param descriptor a statistic descriptor obtained with {@link #nameToDescriptor} or
* {@link StatisticsType#nameToDescriptor}.
* @return the value of the statistic
* @throws IllegalArgumentException If the described statistic does not exist
*/
Number get(StatisticDescriptor descriptor);
/**
* Returns the value of the named statistic.
*
* @param name the name of the statistic
* @return the value of the statistic
* @throws IllegalArgumentException If the named statistic does not exist
*/
Number get(String name);
/**
* Returns the bits that represent the raw value of the described statistic.
*
* @param descriptor a statistic descriptor obtained with {@link #nameToDescriptor} or
* {@link StatisticsType#nameToDescriptor}.
* @return the bits that represent the raw value of the named statistic
* @throws IllegalArgumentException If the described statistic does not exist
*/
long getRawBits(StatisticDescriptor descriptor);
/**
* Returns the bits that represent the raw value of the named statistic.
*
* @param name the name of the statistic
* @return the bits that represent the raw value of the named statistic
* @throws IllegalArgumentException If the named statistic does not exist
*/
long getRawBits(String name);
//////////////////////// inc() Methods ////////////////////////
/**
* Increments the value of the identified statistic of type int by the given amount.
*
* @param id a statistic id obtained with {@link #nameToId} or {@link StatisticsType#nameToId}.
* @param delta the amount by which to increment the statistic value
*
* @throws ArrayIndexOutOfBoundsException If the id is invalid.
* @deprecated as of Geode 1.10, use {@link #incLong(int, long)} instead
*/
@Deprecated
void incInt(int id, int delta);
/**
* Increments the value of the described statistic of type int by the given amount.
*
* @param descriptor the descriptor for the statistic to increment
* @param delta the amount by which to increment the statistic value
* @throws IllegalArgumentException If no statistic exists with the given descriptor
* or if the described statistic is not of type int.
* @deprecated as of Geode 1.10, use {@link #incLong(StatisticDescriptor, long)} instead
*/
@Deprecated
void incInt(StatisticDescriptor descriptor, int delta);
/**
* Increments the value of the statistic of type int with the given name by a given
* amount.
*
* @param name the name of the statistic to increment
* @param delta the amount by which to increment the statistic value
* @throws IllegalArgumentException If no statistic exists with name name or if the
* statistic named name is not of type int.
* @deprecated as of Geode 1.10, use {@link #incLong(String, long)} instead
*/
@Deprecated
void incInt(String name, int delta);
/**
* Increments the value of the identified statistic of type long by the given amount.
*
* @param id a statistic id obtained with {@link #nameToId} or {@link StatisticsType#nameToId}.
* @param delta the amount by which to increment the statistic value
*
* @throws ArrayIndexOutOfBoundsException If the id is invalid.
*/
void incLong(int id, long delta);
/**
* Increments the value of the described statistic of type long by the given amount.
*
* @param descriptor the descriptor for the statistic to increment
* @param delta the amount by which to increment the statistic value
* @throws IllegalArgumentException If no statistic exists with the given descriptor
* or if the described statistic is not of type long.
*/
void incLong(StatisticDescriptor descriptor, long delta);
/**
* Increments the value of the statistic of type long with the given name by a given
* amount.
*
* @param name the name of the statistic to increment
* @param delta the amount by which to increment the statistic value
* @throws IllegalArgumentException If no statistic exists with name name or if the
* statistic named name is not of type long.
*/
void incLong(String name, long delta);
/**
* Increments the value of the identified statistic of type double by the given
* amount.
*
* @param id a statistic id obtained with {@link #nameToId} or {@link StatisticsType#nameToId}.
* @param delta the amount by which to increment the statistic value
*
* @throws ArrayIndexOutOfBoundsException If the id is invalid.
*/
void incDouble(int id, double delta);
/**
* Increments the value of the described statistic of type double by the given
* amount.
*
* @param descriptor the descriptor for the statistic to increment
* @param delta the amount by which to increment the statistic value
*
* @throws IllegalArgumentException If no statistic exists with the given descriptor
* or if the described statistic is not of type double.
*/
void incDouble(StatisticDescriptor descriptor, double delta);
/**
* Increments the value of the statistic of type double with the given name by a
* given amount.
*
* @param name the name of the statistic to increment
* @param delta the amount by which to increment the statistic value
*
* @throws IllegalArgumentException If no statistic exists with name name or if the
* statistic named name is not of type double.
*/
void incDouble(String name, double delta);
/**
* Provide a callback to compute the value of this statistic every sample interval and use that as
* the value of the stat.
*
* The callback should return quickly because it is invoked on a shared thread. It should not do
* any expensive computations, network calls, or access any resources under locks that may be
* locked by long running processes.
*
* This callback will only be invoked if the distributed system property
* statistic-sampling-enabled is set to true, and it will be invoked at intervals determined by
* the statistic-sampling-rate.
*
* Get methods are not guaranteed to recompute a new value, they may return the last sampled value
*
* @param id a statistic id obtained with {@link #nameToId} or {@link StatisticsType#nameToId}.
* @param supplier a callback that will return the value of the stat. This replaces any previously
* registered supplier. If the passed in supplier is null, it will remove any existing
* supplier
* @return the previously registered supplier, or null if there was no previously registered
* supplier
* @throws IllegalArgumentException If the id is invalid.
* @since Geode 1.0
* @deprecated as of Geode 1.10, use {@link #setLongSupplier(int, LongSupplier)} instead
*/
@Deprecated
IntSupplier setIntSupplier(int id, IntSupplier supplier);
/**
* Provide a callback to compute the value of this statistic every sample interval and use that as
* the value of the stat.
*
* The callback should return quickly because it is invoked on a shared thread. It should not do
* any expensive computations, network calls, or access any resources under locks that may be
* locked by long running processes.
*
* This callback will only be invoked if the distributed system property
* statistic-sampling-enabled is set to true, and it will be invoked at intervals determined by
* the statistic-sampling-rate.
*
* Get methods are not guaranteed to recompute a new value, they may return the last sampled value
*
* @param name the name of the statistic to update
* @param supplier a callback that will return the value of the stat. This replaces any previously
* registered supplier. If the passed in supplier is null, it will remove any existing
* supplier
* @return the previously registered supplier, or null if there was no previously registered
* supplier
* @throws IllegalArgumentException If no statistic exists with name name or if the
* statistic named name is not of type int.
* @since Geode 1.0
* @deprecated as of Geode 1.10, use {@link #setLongSupplier(String, LongSupplier)} instead
*/
@Deprecated
IntSupplier setIntSupplier(String name, IntSupplier supplier);
/**
* Provide a callback to compute the value of this statistic every sample interval and use that as
* the value of the stat.
*
* The callback should return quickly because it is invoked on a shared thread. It should not do
* any expensive computations, network calls, or access any resources under locks that may be
* locked by long running processes.
*
* This callback will only be invoked if the distributed system property
* statistic-sampling-enabled is set to true, and it will be invoked at intervals determined by
* the statistic-sampling-rate.
*
* Get methods are not guaranteed to recompute a new value, they may return the last sampled value
*
* @param descriptor the descriptor of the statistic to update
* @param supplier a callback that will return the value of the stat. This replaces any previously
* registered supplier. If the passed in supplier is null, it will remove any existing
* supplier
* @return the previously registered supplier, or null if there was no previously registered
* supplier
* @throws IllegalArgumentException If no statistic exists with the given descriptor
* or if the described statistic is not of type int.
* @since Geode 1.0
* @deprecated as of Geode 1.10, use {@link #setLongSupplier(StatisticDescriptor, LongSupplier)}
* instead
*/
@Deprecated
IntSupplier setIntSupplier(StatisticDescriptor descriptor, IntSupplier supplier);
/**
* Provide a callback to compute the value of this statistic every sample interval and use that as
* the value of the stat.
*
* The callback should return quickly because it is invoked on a shared thread. It should not do
* any expensive computations, network calls, or access any resources under locks that may be
* locked by long running processes.
*
* This callback will only be invoked if the distributed system property
* statistic-sampling-enabled is set to true, and it will be invoked at intervals determined by
* the statistic-sampling-rate.
*
* Get methods are not guaranteed to recompute a new value, they may return the last sampled value
*
* @param id a statistic id obtained with {@link #nameToId} or {@link StatisticsType#nameToId}.
* @param supplier a callback that will return the value of the stat. This replaces any previously
* registered supplier. If the passed in supplier is null, it will remove any existing
* supplier
* @return the previously registered supplier, or null if there was no previously registered
* supplier
* @throws IllegalArgumentException If the id is invalid.
* @since Geode 1.0
*/
LongSupplier setLongSupplier(int id, LongSupplier supplier);
/**
* Provide a callback to compute the value of this statistic every sample interval and use that as
* the value of the stat.
*
* The callback should return quickly because it is invoked on a shared thread. It should not do
* any expensive computations, network calls, or access any resources under locks that may be
* locked by long running processes.
*
* This callback will only be invoked if the distributed system property
* statistic-sampling-enabled is set to true, and it will be invoked at intervals determined by
* the statistic-sampling-rate.
*
* Get methods are not guaranteed to recompute a new value, they may return the last sampled value
*
* @param name the name of the statistic to update
* @param supplier a callback that will return the value of the stat. This replaces any previously
* registered supplier. If the passed in supplier is null, it will remove any existing
* supplier
* @return the previously registered supplier, or null if there was no previously registered
* supplier
* @throws IllegalArgumentException If no statistic exists with name name or if the
* statistic named name is not of type long.
*/
LongSupplier setLongSupplier(String name, LongSupplier supplier);
/**
* Provide a callback to compute the value of this statistic every sample interval and use that as
* the value of the stat.
*
* The callback should return quickly because it is invoked on a shared thread. It should not do
* any expensive computations, network calls, or access any resources under locks that may be
* locked by long running processes.
*
* This callback will only be invoked if the distributed system property
* statistic-sampling-enabled is set to true, and it will be invoked at intervals determined by
* the statistic-sampling-rate.
*
* Get methods are not guaranteed to recompute a new value, they may return the last sampled value
*
* @param descriptor the descriptor of the statistic to update
* @param supplier a callback that will return the value of the stat. This replaces any previously
* registered supplier. If the passed in supplier is null, it will remove any existing
* supplier
* @return the previously registered supplier, or null if there was no previously registered
* supplier
* @throws IllegalArgumentException If no statistic exists with the given descriptor
* or if the described statistic is not of type long.
* @since Geode 1.0
*/
LongSupplier setLongSupplier(StatisticDescriptor descriptor, LongSupplier supplier);
/**
* Provide a callback to compute the value of this statistic every sample interval and use that as
* the value of the stat.
*
* The callback should return quickly because it is invoked on a shared thread. It should not do
* any expensive computations, network calls, or access any resources under locks that may be
* locked by double running processes.
*
* This callback will only be invoked if the distributed system property
* statistic-sampling-enabled is set to true, and it will be invoked at intervals determined by
* the statistic-sampling-rate.
*
* Get methods are not guaranteed to recompute a new value, they may return the last sampled value
*
* @param id a statistic id obtained with {@link #nameToId} or {@link StatisticsType#nameToId}.
* @param supplier a callback that will return the value of the stat. This replaces any previously
* registered supplier. If the passed in supplier is null, it will remove any existing
* supplier
* @return the previously registered supplier, or null if there was no previously registered
* supplier
* @throws IllegalArgumentException If the id is invalid.
* @since Geode 1.0
*/
DoubleSupplier setDoubleSupplier(int id, DoubleSupplier supplier);
/**
* Provide a callback to compute the value of this statistic every sample interval and use that as
* the value of the stat.
*
* The callback should return quickly because it is invoked on a shared thread. It should not do
* any expensive computations, network calls, or access any resources under locks that may be
* locked by double running processes.
*
* This callback will only be invoked if the distributed system property
* statistic-sampling-enabled is set to true, and it will be invoked at intervals determined by
* the statistic-sampling-rate.
*
* Get methods are not guaranteed to recompute a new value, they may return the last sampled value
*
* @param name the name of the statistic to update
* @param supplier a callback that will return the value of the stat. This replaces any previously
* registered supplier. If the passed in supplier is null, it will remove any existing
* supplier
* @return the previously registered supplier, or null if there was no previously registered
* supplier
* @throws IllegalArgumentException If no statistic exists with name name or if the
* statistic named name is not of type double.
* @since Geode 1.0
*/
DoubleSupplier setDoubleSupplier(String name, DoubleSupplier supplier);
/**
* Provide a callback to compute the value of this statistic every sample interval and use that as
* the value of the stat.
*
* The callback should return quickly because it is invoked on a shared thread. It should not do
* any expensive computations, network calls, or access any resources under locks that may be
* locked by double running processes.
*
* This callback will only be invoked if the distributed system property
* statistic-sampling-enabled is set to true, and it will be invoked at intervals determined by
* the statistic-sampling-rate.
*
* Get methods are not guaranteed to recompute a new value, they may return the last sampled value
*
* @param descriptor the descriptor of the statistic to update
* @param supplier a callback that will return the value of the stat. This replaces any previously
* registered supplier. If the passed in supplier is null, it will remove any existing
* supplier
* @return the previously registered supplier, or null if there was no previously registered
* supplier
* @throws IllegalArgumentException If no statistic exists with the given descriptor
* or if the described statistic is not of type double.
* @since Geode 1.0
*/
DoubleSupplier setDoubleSupplier(StatisticDescriptor descriptor, DoubleSupplier supplier);
}