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}