001/*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements.  See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership.  The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License.  You may obtain a copy of the License at
009 *
010 *     http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing, software
013 * distributed under the License is distributed on an "AS IS" BASIS,
014 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015 * See the License for the specific language governing permissions and
016 * limitations under the License.
017 */
018package org.apache.hadoop.hbase.metrics;
019
020import java.util.Optional;
021import org.apache.hadoop.hbase.HBaseInterfaceAudience;
022import org.apache.yetus.audience.InterfaceAudience;
023import org.apache.yetus.audience.InterfaceStability;
024
025/**
026 * General purpose factory for creating various metrics.
027 */
028@InterfaceAudience.LimitedPrivate(HBaseInterfaceAudience.COPROC)
029@InterfaceStability.Evolving
030public interface MetricRegistry extends MetricSet {
031
032  /**
033   * Get or construct a {@link Timer} used to measure durations and report rates.
034   * @param name the name of the timer.
035   * @return An instance of {@link Timer}.
036   */
037  Timer timer(String name);
038
039  /**
040   * Get or construct a {@link Histogram} used to measure a distribution of values.
041   * @param name The name of the Histogram.
042   * @return An instance of {@link Histogram}.
043   */
044  Histogram histogram(String name);
045
046  /**
047   * Get or construct a {@link Meter} used to measure durations and report distributions (a
048   * combination of a {@link Timer} and a {@link Histogram}.
049   * @param name The name of the Meter.
050   * @return An instance of {@link Meter}.
051   */
052  Meter meter(String name);
053
054  /**
055   * Get or construct a {@link Counter} used to track a mutable number.
056   * @param name The name of the Counter
057   * @return An instance of {@link Counter}.
058   */
059  Counter counter(String name);
060
061  /**
062   * Register a {@link Gauge}. The Gauge will be invoked at a period defined by the implementation
063   * of {@link MetricRegistry}.
064   * @param name  The name of the Gauge.
065   * @param gauge A callback to compute the current value.
066   * @return the registered gauge, or the existing gauge
067   */
068  <T> Gauge<T> register(String name, Gauge<T> gauge);
069
070  /**
071   * Registers the {@link Metric} with the given name if there does not exist one with the same
072   * name. Returns the newly registered or existing Metric.
073   * @param name   The name of the Metric.
074   * @param metric the metric to register
075   * @return the registered metric, or the existing metrid
076   */
077  Metric register(String name, Metric metric);
078
079  /**
080   * Registers the {@link Metric}s in the given MetricSet.
081   * @param metricSet set of metrics to register.
082   */
083  void registerAll(MetricSet metricSet);
084
085  /**
086   * Returns previously registered metric with the name if any.
087   * @param name the name of the metric
088   * @return previously registered metric
089   */
090  Optional<Metric> get(String name);
091
092  /**
093   * Removes the metric with the given name.
094   * @param name the name of the metric
095   * @return true if the metric is removed.
096   */
097  boolean remove(String name);
098
099  /**
100   * Removes the metric with the given name only if it is registered to the provided metric.
101   * @param name   the name of the metric
102   * @param metric the metric expected to be registered to the given name
103   * @return true if the metric is removed.
104   */
105  boolean remove(String name, Metric metric);
106
107  /**
108   * Return the MetricRegistryInfo object for this registry.
109   * @return MetricRegistryInfo describing the registry.
110   */
111  @InterfaceAudience.Private
112  MetricRegistryInfo getMetricRegistryInfo();
113}