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 */
018
019package org.apache.hadoop.metrics2.lib;
020
021import org.apache.commons.lang.StringUtils;
022import org.apache.hadoop.classification.InterfaceAudience;
023import org.apache.hadoop.classification.InterfaceStability;
024import org.apache.hadoop.metrics2.MetricsInfo;
025import org.apache.hadoop.metrics2.MetricsRecordBuilder;
026import org.apache.hadoop.metrics2.util.SampleStat;
027import static org.apache.hadoop.metrics2.lib.Interns.*;
028
029/**
030 * A mutable metric with stats.
031 *
032 * Useful for keeping throughput/latency stats.
033 */
034@InterfaceAudience.Public
035@InterfaceStability.Evolving
036public class MutableStat extends MutableMetric {
037  private final MetricsInfo numInfo;
038  private final MetricsInfo avgInfo;
039  private final MetricsInfo stdevInfo;
040  private final MetricsInfo iMinInfo;
041  private final MetricsInfo iMaxInfo;
042  private final MetricsInfo minInfo;
043  private final MetricsInfo maxInfo;
044
045  private final SampleStat intervalStat = new SampleStat();
046  private final SampleStat prevStat = new SampleStat();
047  private final SampleStat.MinMax minMax = new SampleStat.MinMax();
048  private long numSamples = 0;
049  private boolean extended = false;
050
051  /**
052   * Construct a sample statistics metric
053   * @param name        of the metric
054   * @param description of the metric
055   * @param sampleName  of the metric (e.g. "Ops")
056   * @param valueName   of the metric (e.g. "Time", "Latency")
057   * @param extended    create extended stats (stdev, min/max etc.) by default.
058   */
059  public MutableStat(String name, String description,
060                     String sampleName, String valueName, boolean extended) {
061    String ucName = StringUtils.capitalize(name);
062    String usName = StringUtils.capitalize(sampleName);
063    String uvName = StringUtils.capitalize(valueName);
064    String desc = StringUtils.uncapitalize(description);
065    String lsName = StringUtils.uncapitalize(sampleName);
066    String lvName = StringUtils.uncapitalize(valueName);
067    numInfo = info(ucName +"Num"+ usName, "Number of "+ lsName +" for "+ desc);
068    avgInfo = info(ucName +"Avg"+ uvName, "Average "+ lvName +" for "+ desc);
069    stdevInfo = info(ucName +"Stdev"+ uvName,
070                     "Standard deviation of "+ lvName +" for "+ desc);
071    iMinInfo = info(ucName +"IMin"+ uvName,
072                    "Interval min "+ lvName +" for "+ desc);
073    iMaxInfo = info(ucName + "IMax"+ uvName,
074                    "Interval max "+ lvName +" for "+ desc);
075    minInfo = info(ucName +"Min"+ uvName, "Min "+ lvName +" for "+ desc);
076    maxInfo = info(ucName +"Max"+ uvName, "Max "+ lvName +" for "+ desc);
077    this.extended = extended;
078  }
079
080  /**
081   * Construct a snapshot stat metric with extended stat off by default
082   * @param name        of the metric
083   * @param description of the metric
084   * @param sampleName  of the metric (e.g. "Ops")
085   * @param valueName   of the metric (e.g. "Time", "Latency")
086   */
087  public MutableStat(String name, String description,
088                     String sampleName, String valueName) {
089    this(name, description, sampleName, valueName, false);
090  }
091
092  /**
093   * Add a number of samples and their sum to the running stat
094   * @param numSamples  number of samples
095   * @param sum of the samples
096   */
097  public synchronized void add(long numSamples, long sum) {
098    intervalStat.add(numSamples, sum);
099    setChanged();
100  }
101
102  /**
103   * Add a snapshot to the metric
104   * @param value of the metric
105   */
106  public synchronized void add(long value) {
107    intervalStat.add(value);
108    minMax.add(value);
109    setChanged();
110  }
111
112  public synchronized void snapshot(MetricsRecordBuilder builder, boolean all) {
113    if (all || changed()) {
114      numSamples += intervalStat.numSamples();
115      builder.addCounter(numInfo, numSamples)
116             .addGauge(avgInfo, lastStat().mean());
117      if (extended) {
118        builder.addGauge(stdevInfo, lastStat().stddev())
119               .addGauge(iMinInfo, lastStat().min())
120               .addGauge(iMaxInfo, lastStat().max())
121               .addGauge(minInfo, minMax.min())
122               .addGauge(maxInfo, minMax.max());
123      }
124      if (changed()) {
125        if (numSamples > 0) {
126          intervalStat.copyTo(prevStat);
127          intervalStat.reset();
128        }
129        clearChanged();
130      }
131    }
132  }
133
134  private SampleStat lastStat() {
135    return changed() ? intervalStat : prevStat;
136  }
137
138  /**
139   * Reset the all time min max of the metric
140   */
141  public void resetMinMax() {
142    minMax.reset();
143  }
144
145}