1 /* 2 * Copyright 2018, OpenCensus Authors 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 package io.opencensus.metrics; 18 19 import io.opencensus.common.ExperimentalApi; 20 import io.opencensus.common.ToDoubleFunction; 21 import io.opencensus.common.ToLongFunction; 22 import io.opencensus.internal.Utils; 23 import java.util.List; 24 25 /** 26 * Creates and manages your application's set of metrics. The default implementation of this creates 27 * a {@link io.opencensus.metrics.export.MetricProducer} and registers it to the global {@link 28 * io.opencensus.metrics.export.MetricProducerManager}. 29 * 30 * @since 0.17 31 */ 32 @ExperimentalApi 33 public abstract class MetricRegistry { 34 /** 35 * This will be removed in 0.22. 36 * 37 * @deprecated since 0.20, use {@link #addLongGauge(String, MetricOptions)}. 38 * @since 0.17 39 */ 40 @Deprecated addLongGauge( String name, String description, String unit, List<LabelKey> labelKeys)41 public LongGauge addLongGauge( 42 String name, String description, String unit, List<LabelKey> labelKeys) { 43 return addLongGauge( 44 name, 45 MetricOptions.builder() 46 .setDescription(description) 47 .setUnit(unit) 48 .setLabelKeys(labelKeys) 49 .build()); 50 } 51 52 /** 53 * Builds a new long gauge to be added to the registry. This is a more convenient form when you 54 * want to manually increase and decrease values as per your service requirements. 55 * 56 * @param name the name of the metric. 57 * @param options the options for the metric. 58 * @return a {@code LongGauge}. 59 * @throws NullPointerException if {@code name} is null. 60 * @throws IllegalArgumentException if different metric with the same name already registered. 61 * @since 0.20 62 */ 63 @ExperimentalApi addLongGauge(String name, MetricOptions options)64 public abstract LongGauge addLongGauge(String name, MetricOptions options); 65 66 /** 67 * This will be removed in 0.22. 68 * 69 * @deprecated since 0.20, use {@link #addDoubleGauge(String, MetricOptions)}. 70 * @since 0.17 71 */ 72 @Deprecated addDoubleGauge( String name, String description, String unit, List<LabelKey> labelKeys)73 public DoubleGauge addDoubleGauge( 74 String name, String description, String unit, List<LabelKey> labelKeys) { 75 return addDoubleGauge( 76 name, 77 MetricOptions.builder() 78 .setDescription(description) 79 .setUnit(unit) 80 .setLabelKeys(labelKeys) 81 .build()); 82 } 83 84 /** 85 * Builds a new double gauge to be added to the registry. This is a more convenient form when you 86 * want to manually increase and decrease values as per your service requirements. 87 * 88 * @param name the name of the metric. 89 * @param options the options for the metric. 90 * @return a {@code DoubleGauge}. 91 * @throws NullPointerException if {@code name} is null. 92 * @throws IllegalArgumentException if different metric with the same name already registered. 93 * @since 0.20 94 */ 95 @ExperimentalApi addDoubleGauge(String name, MetricOptions options)96 public abstract DoubleGauge addDoubleGauge(String name, MetricOptions options); 97 98 /** 99 * This will be removed in 0.22. 100 * 101 * @deprecated since 0.20, use {@link #addDerivedLongGauge(String, MetricOptions)}. 102 * @since 0.17 103 */ 104 @Deprecated addDerivedLongGauge( String name, String description, String unit, List<LabelKey> labelKeys)105 public DerivedLongGauge addDerivedLongGauge( 106 String name, String description, String unit, List<LabelKey> labelKeys) { 107 return addDerivedLongGauge( 108 name, 109 MetricOptions.builder() 110 .setDescription(description) 111 .setUnit(unit) 112 .setLabelKeys(labelKeys) 113 .build()); 114 } 115 116 /** 117 * Builds a new derived long gauge to be added to the registry. This is a more convenient form 118 * when you want to define a gauge by executing a {@link ToLongFunction} on an object. 119 * 120 * @param name the name of the metric. 121 * @param options the options for the metric. 122 * @return a {@code DerivedLongGauge}. 123 * @throws NullPointerException if {@code name} is null. 124 * @throws IllegalArgumentException if different metric with the same name already registered. 125 * @since 0.17 126 */ 127 @ExperimentalApi addDerivedLongGauge(String name, MetricOptions options)128 public abstract DerivedLongGauge addDerivedLongGauge(String name, MetricOptions options); 129 130 /** 131 * This will be removed in 0.22. 132 * 133 * @deprecated since 0.20, use {@link #addDerivedDoubleGauge(String, MetricOptions)}. 134 * @since 0.17 135 */ 136 @Deprecated addDerivedDoubleGauge( String name, String description, String unit, List<LabelKey> labelKeys)137 public DerivedDoubleGauge addDerivedDoubleGauge( 138 String name, String description, String unit, List<LabelKey> labelKeys) { 139 return addDerivedDoubleGauge( 140 name, 141 MetricOptions.builder() 142 .setDescription(description) 143 .setUnit(unit) 144 .setLabelKeys(labelKeys) 145 .build()); 146 } 147 148 /** 149 * Builds a new derived double gauge to be added to the registry. This is a more convenient form 150 * when you want to define a gauge by executing a {@link ToDoubleFunction} on an object. 151 * 152 * @param name the name of the metric. 153 * @param options the options for the metric. 154 * @return a {@code DerivedDoubleGauge}. 155 * @throws NullPointerException if {@code name} is null. 156 * @throws IllegalArgumentException if different metric with the same name already registered. 157 * @since 0.17 158 */ 159 @ExperimentalApi addDerivedDoubleGauge(String name, MetricOptions options)160 public abstract DerivedDoubleGauge addDerivedDoubleGauge(String name, MetricOptions options); 161 162 /** 163 * Builds a new long cumulative to be added to the registry. This is a more convenient form when 164 * you want to manually increase values as per your service requirements. 165 * 166 * @param name the name of the metric. 167 * @param options the options for the metric. 168 * @return a {@code LongCumulative}. 169 * @throws NullPointerException if {@code name} is null. 170 * @throws IllegalArgumentException if different metric with the same name already registered. 171 * @since 0.21 172 */ 173 @ExperimentalApi addLongCumulative(String name, MetricOptions options)174 public abstract LongCumulative addLongCumulative(String name, MetricOptions options); 175 176 /** 177 * Builds a new double cumulative to be added to the registry. This is a more convenient form when 178 * you want to manually increase values as per your service requirements. 179 * 180 * @param name the name of the metric. 181 * @param options the options for the metric. 182 * @return a {@code DoubleCumulative}. 183 * @throws NullPointerException if {@code name} is null. 184 * @throws IllegalArgumentException if different metric with the same name already registered. 185 * @since 0.21 186 */ 187 @ExperimentalApi addDoubleCumulative(String name, MetricOptions options)188 public abstract DoubleCumulative addDoubleCumulative(String name, MetricOptions options); 189 190 /** 191 * Builds a new derived long cumulative to be added to the registry. This is a more convenient 192 * form when you want to define a cumulative by executing a {@link ToLongFunction} on an object. 193 * 194 * @param name the name of the metric. 195 * @param options the options for the metric. 196 * @return a {@code DerivedLongCumulative}. 197 * @throws NullPointerException if {@code name} is null. 198 * @throws IllegalArgumentException if different metric with the same name already registered. 199 * @since 0.21 200 */ 201 @ExperimentalApi addDerivedLongCumulative( String name, MetricOptions options)202 public abstract DerivedLongCumulative addDerivedLongCumulative( 203 String name, MetricOptions options); 204 205 /** 206 * Builds a new derived double cumulative to be added to the registry. This is a more convenient 207 * form when you want to define a cumulative by executing a {@link ToDoubleFunction} on an object. 208 * 209 * @param name the name of the metric. 210 * @param options the options for the metric. 211 * @return a {@code DerivedDoubleCumulative}. 212 * @throws NullPointerException if {@code name} is null. 213 * @throws IllegalArgumentException if different metric with the same name already registered. 214 * @since 0.21 215 */ 216 @ExperimentalApi addDerivedDoubleCumulative( String name, MetricOptions options)217 public abstract DerivedDoubleCumulative addDerivedDoubleCumulative( 218 String name, MetricOptions options); 219 newNoopMetricRegistry()220 static MetricRegistry newNoopMetricRegistry() { 221 return new NoopMetricRegistry(); 222 } 223 224 private static final class NoopMetricRegistry extends MetricRegistry { 225 226 @Override addLongGauge(String name, MetricOptions options)227 public LongGauge addLongGauge(String name, MetricOptions options) { 228 return LongGauge.newNoopLongGauge( 229 Utils.checkNotNull(name, "name"), 230 options.getDescription(), 231 options.getUnit(), 232 options.getLabelKeys()); 233 } 234 235 @Override addDoubleGauge(String name, MetricOptions options)236 public DoubleGauge addDoubleGauge(String name, MetricOptions options) { 237 return DoubleGauge.newNoopDoubleGauge( 238 Utils.checkNotNull(name, "name"), 239 options.getDescription(), 240 options.getUnit(), 241 options.getLabelKeys()); 242 } 243 244 @Override addDerivedLongGauge(String name, MetricOptions options)245 public DerivedLongGauge addDerivedLongGauge(String name, MetricOptions options) { 246 return DerivedLongGauge.newNoopDerivedLongGauge( 247 Utils.checkNotNull(name, "name"), 248 options.getDescription(), 249 options.getUnit(), 250 options.getLabelKeys()); 251 } 252 253 @Override addDerivedDoubleGauge(String name, MetricOptions options)254 public DerivedDoubleGauge addDerivedDoubleGauge(String name, MetricOptions options) { 255 return DerivedDoubleGauge.newNoopDerivedDoubleGauge( 256 Utils.checkNotNull(name, "name"), 257 options.getDescription(), 258 options.getUnit(), 259 options.getLabelKeys()); 260 } 261 262 @Override addLongCumulative(String name, MetricOptions options)263 public LongCumulative addLongCumulative(String name, MetricOptions options) { 264 return LongCumulative.newNoopLongCumulative( 265 Utils.checkNotNull(name, "name"), 266 options.getDescription(), 267 options.getUnit(), 268 options.getLabelKeys()); 269 } 270 271 @Override addDoubleCumulative(String name, MetricOptions options)272 public DoubleCumulative addDoubleCumulative(String name, MetricOptions options) { 273 return DoubleCumulative.newNoopDoubleCumulative( 274 Utils.checkNotNull(name, "name"), 275 options.getDescription(), 276 options.getUnit(), 277 options.getLabelKeys()); 278 } 279 280 @Override addDerivedLongCumulative(String name, MetricOptions options)281 public DerivedLongCumulative addDerivedLongCumulative(String name, MetricOptions options) { 282 return DerivedLongCumulative.newNoopDerivedLongCumulative( 283 Utils.checkNotNull(name, "name"), 284 options.getDescription(), 285 options.getUnit(), 286 options.getLabelKeys()); 287 } 288 289 @Override addDerivedDoubleCumulative(String name, MetricOptions options)290 public DerivedDoubleCumulative addDerivedDoubleCumulative(String name, MetricOptions options) { 291 return DerivedDoubleCumulative.newNoopDerivedDoubleCumulative( 292 Utils.checkNotNull(name, "name"), 293 options.getDescription(), 294 options.getUnit(), 295 options.getLabelKeys()); 296 } 297 } 298 } 299