com.hp.sdn.adm.metric

Interface MetricService

public interface MetricService

Interface for interacting with the Metering service within the controller.

Author:

Steve Britt, Nadeea Mendoza

Field Summary

Fields

Modifier and Type	Field and Description
static String	WILDCARD Constant the represents a wildcard parameter during communication between metering REST and business logic layers.

Method Summary

Methods

Modifier and Type	Method and Description
void	configureAgingDays(int days) Method that can be called to change the metering configuration for how long persisted data is retained.
TimeStampedCounter	createCounter(CounterDescriptor descriptor) Returns a new TimeStampedCounter object based upon the provided CounterDescriptor.
TimeStampedGauge	createGauge(GaugeDescriptor descriptor) Returns a new TimeStampedGauge object based upon the provided GaugeDescriptor.
TimeStampedHistogram	createHistogram(HistogramDescriptor descriptor) Returns a new TimeStampedHistogram object based upon the provided HistogramDescriptor.
TimeStampedMeter	createMeter(MeterDescriptor descriptor) Returns a new TimeStampedMeter object based upon the provided MeterDescriptor.
TimeStampedRatioGauge	createRatioGauge(RatioGaugeDescriptor descriptor) Returns a new TimeStampedRatioGauge object based upon the provided RatioGaugeDescriptor.
TimeStampedRollingCounter	createRollingCounter(RollingCounterDescriptor descriptor) Returns a new TimeStampedRollingCounter object based upon the provided RollingCounterDescriptor.
TimeStampedTimer	createTimer(TimerDescriptor descriptor) Returns a new TimeStampedTimer object based upon the provided TimerDescriptor.
Map<String,String>	getApplications() Returns application IDs and names for applications that have metrics persisted for them.
MetricDescriptor	getMetric(String uid) Returns the descriptor details of an existing metric if found
Set<String>	getMetricNames(String appId, String primaryTag, String secondaryTag) Returns metric names associated with the application ID, primary tag, and secondary tag.
Map<MetricDescriptor,String>	getPersistedMetrics(String appId, String primaryTag, String secondaryTag, String name) Returns all persisted metrics registered and available from the specified application, primaryTag, secondaryTag and metric name.
Set<String>	getPrimaryTags(String appId, String name) Returns primary tags associated with the application ID and metric name.
Set<String>	getSecondaryTags(String appId, String name, String primaryTag) Returns secondary tags associated with the application ID, primary tag, and metric name.
String	getUid(String appId, String name, String primaryTag, String secondaryTag) Returns the UID of the specific metric identified by an application ID, metric name, primary tag, and secondary tag.
Set<String>	getUids(String appId) Returns metric UIDs associated with an application ID.
Set<String>	getUids(String appId, String name) Returns metric UIDs associated with the application ID and metric name.
Set<String>	getUids(String appId, String name, String primaryTag) Returns metric UIDs associated with the application ID, primary tag, and metric name.
MetricValue	getValue(String uid) Returns the latest MetricValue based on the specified metric UID.
List<MetricValue>	getValues(String uid, Date beginDate, Date endDate, long interval) Returns MetricValues based on the specified metric UID, the time range, and the summary interval.
TimeStampedMetric	recreateMetric(String uid) Recreates a previously existing TimeStampedMetric with the specified UID.
void	registerMetric(TimeStampedMetric toRegister) Registers an existing TimeStampedMetric with the metering framework.
void	removeMetric(TimeStampedMetric toRemove) Removes an existing TimeStampedMetric object from the metering framework, essentially unregistering it so that the framework no longer processes its values.

Field Detail

WILDCARD

static final String WILDCARD

Constant the represents a wildcard parameter during communication between metering REST and business logic layers.

See Also:

Constant Field Values

Method Detail

configureAgingDays

void configureAgingDays(int days)

Method that can be called to change the metering configuration for how long persisted data is retained.

Parameters:

days - the number of days to age the data

createCounter

TimeStampedCounter createCounter(CounterDescriptor descriptor)

Returns a new TimeStampedCounter object based upon the provided CounterDescriptor.

Parameters:

descriptor - CounterDescriptor initialized to embody the desired properties of the TimeStampedCounter to be created

Returns:

resultant TimeStampedCounter object

createGauge

TimeStampedGauge createGauge(GaugeDescriptor descriptor)

Returns a new TimeStampedGauge object based upon the provided GaugeDescriptor.

Parameters:

descriptor - GaugeDescriptor initialized to embody the desired properties of the TimeStampedGauge to be created

Returns:

resultant TimeStampedGauge object

createHistogram

TimeStampedHistogram createHistogram(HistogramDescriptor descriptor)

Returns a new TimeStampedHistogram object based upon the provided HistogramDescriptor.

Parameters:

descriptor - HistogramDescriptor initialized to embody the desired properties of the TimeStampedHistogram to be created

Returns:

resultant TimeStampedHistogram object

createMeter

TimeStampedMeter createMeter(MeterDescriptor descriptor)

Returns a new TimeStampedMeter object based upon the provided MeterDescriptor.

Parameters:

descriptor - MeterDescriptor initialized to embody the desired properties of the TimeStampedMeter to be created

Returns:

resultant TimeStampedMeter object

createRatioGauge

TimeStampedRatioGauge createRatioGauge(RatioGaugeDescriptor descriptor)

Returns a new TimeStampedRatioGauge object based upon the provided RatioGaugeDescriptor.

Parameters:

descriptor - RatioGaugeDescriptor initialized to embody the desired properties of the TimeStampedRatioGauge to be created

Returns:

resultant TimeStampedRatioGauge object

createRollingCounter

TimeStampedRollingCounter createRollingCounter(RollingCounterDescriptor descriptor)

Returns a new TimeStampedRollingCounter object based upon the provided RollingCounterDescriptor.

Parameters:

descriptor - RollingCounterDescriptor initialized to embody the desired properties of the TimeStampedRollingCounter to be created

Returns:

resultant TimeStampedRollingCounter object

createTimer

TimeStampedTimer createTimer(TimerDescriptor descriptor)

Returns a new TimeStampedTimer object based upon the provided TimerDescriptor.

Parameters:

descriptor - TimerDescriptor initialized to embody the desired properties of the TimeStampedTimer to be created

Returns:

resultant TimeStampedTimer object

getPersistedMetrics

Map<MetricDescriptor,String> getPersistedMetrics(String appId,
                                               String primaryTag,
                                               String secondaryTag,
                                               String name)

Returns all persisted metrics registered and available from the specified application, primaryTag, secondaryTag and metric name.

Parameters:

appId - application ID to filter the results with; if no value is specified the ID corresponding to the base controller will be used

primaryTag - primary tag to filter the results with; if no value is specified a default value will be used

secondaryTag - secondary tag to filter the results with; if no value is specified a default value will be used

name - metric name to filter the results with; if no value is specified this field will be ignored

Returns:

Map of MetricDescriptors

getMetric

MetricDescriptor getMetric(String uid)

Returns the descriptor details of an existing metric if found

Parameters:

uid - The unique metric identifier

Returns:

MetricDescriptor

getApplications

Map<String,String> getApplications()

Returns application IDs and names for applications that have metrics persisted for them. Includes applications with metrics that have readable values which have not been aged (i.e. metrics that still have data on disk but may or may not be actively updated).

Returns:

Map of application IDs to application names

getMetricNames

Set<String> getMetricNames(String appId,
                         String primaryTag,
                         String secondaryTag)

Returns metric names associated with the application ID, primary tag, and secondary tag.

Parameters:

appId - application ID

primaryTag - primary tag associated with the metric; may be the reserved WILDCARD value or may be null

secondaryTag - secondary tag associated with the metric; may be the reserved WILDCARD value or may be null

Returns:

Set of metric names associated with the application ID, primary tag, and secondary tag

getPrimaryTags

Set<String> getPrimaryTags(String appId,
                         String name)

Returns primary tags associated with the application ID and metric name.

Parameters:

appId - application ID

name - metric name; may be the reserved WILDCARD value

Returns:

Set of primary tags associated with the specific application and name

getSecondaryTags

Set<String> getSecondaryTags(String appId,
                           String name,
                           String primaryTag)

Returns secondary tags associated with the application ID, primary tag, and metric name.

Parameters:

appId - application ID

name - metric name; may be the reserved WILDCARD value

primaryTag - primary tag associated with the metric; may be the reserved WILDCARD value or may be null

Returns:

Set of secondary tags associated with the application ID, metric name, and primary tag

getUid

String getUid(String appId,
            String name,
            String primaryTag,
            String secondaryTag)

Returns the UID of the specific metric identified by an application ID, metric name, primary tag, and secondary tag.

Parameters:

appId - application ID

name - metric name

primaryTag - primary tag

secondaryTag - secondary tag

Returns:

metric UID

getUids

Set<String> getUids(String appId)

Returns metric UIDs associated with an application ID.

Parameters:

appId - application ID

Returns:

Set of metric UIDs

getUids

Set<String> getUids(String appId,
                  String name)

Returns metric UIDs associated with the application ID and metric name.

Parameters:

appId - application ID

name - metric name

Returns:

Set of metric UIDs

getUids

Set<String> getUids(String appId,
                  String name,
                  String primaryTag)

Returns metric UIDs associated with the application ID, primary tag, and metric name.

Parameters:

appId - application ID

name - metric name

primaryTag - primary tag

Returns:

Set of metric UIDs

getValue

MetricValue getValue(String uid)
                     throws DataFormatException,
                            IOException

Returns the latest MetricValue based on the specified metric UID.

Parameters:

uid - metric UID

Returns:

latest MetricValue for the specified metric

Throws:

InvalidParameterException - if the corresponding metric identifier does not exist

DataFormatException - if the expected file content cannot be read

IOException - if the expected file cannot be accessed

getValues

List<MetricValue> getValues(String uid,
                          Date beginDate,
                          Date endDate,
                          long interval)
                            throws DataFormatException,
                                   IOException

Returns MetricValues based on the specified metric UID, the time range, and the summary interval.

Parameters:

uid - metric UID

beginDate - first date to include values from

endDate - last date to include values from

interval - summary interval in minute(s)

Returns:

List of MetricValues

Throws:

InvalidParameterException - if the corresponding metric identifier does not exist

DataFormatException - if the expected file content cannot be read

IOException - if the expected file cannot be accessed

recreateMetric

TimeStampedMetric recreateMetric(String uid)

Recreates a previously existing TimeStampedMetric with the specified UID. Should the metering framework bounce while other controller components stay up, those components will still have references to UIDs of TimeStampedMetric objects allocated before the framework went down. To ensure that the metering framework processes such TimeStampedMetrics properly for persistence, JMX exposure, etc. after the framework comes back up they should be re-created within the metering framework after it comes back up.

Parameters:

uid - UID of a previously existing TimeStampedMetric

Returns:

a new TimeStampedMetric created with the specified UID

registerMetric

void registerMetric(TimeStampedMetric toRegister)

Registers an existing TimeStampedMetric with the metering framework. Should the metering framework bounce while other controller components stay up, those components will still have references to TimeStampedMetric objects allocated before the framework went down. To ensure that the metering framework processes such TimeStampedMetrics properly for persistence, JMX exposure, etc. after the framework comes back up they should be re-registered with the metering framework after it comes back up.

Parameters:

toRegister - TimeStampedMetric to re-register

removeMetric

void removeMetric(TimeStampedMetric toRemove)

Removes an existing TimeStampedMetric object from the metering framework, essentially unregistering it so that the framework no longer processes its values. If the TimeStampedMetric was exposed via JMX it will be removed from the JMX server. Values already persisted for the TimeStampedMetric will not be altered, but will be allowed to eventually age out if the TimeStampedMetric is not eventually re-registered to provide new values.

Parameters:

toRemove - TimeStampedMetric to remove from the metering framework