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 * Builds a new long gauge to be added to the registry. This is more convenient form when you want 36 * to manually increase and decrease values as per your service requirements. 37 * 38 * @param name the name of the metric. 39 * @param description the description of the metric. 40 * @param unit the unit of the metric. 41 * @param labelKeys the list of the label keys. 42 * @throws NullPointerException if {@code labelKeys} is null OR any element of {@code labelKeys} 43 * is null OR {@code name}, {@code description}, {@code unit} is null. 44 * @throws IllegalArgumentException if different metric with the same name already registered. 45 * @since 0.17 46 */ 47 @ExperimentalApi addLongGauge( String name, String description, String unit, List<LabelKey> labelKeys)48 public abstract LongGauge addLongGauge( 49 String name, String description, String unit, List<LabelKey> labelKeys); 50 51 /** 52 * Builds a new double gauge to be added to the registry. This is more convenient form when you 53 * want to manually increase and decrease values as per your service requirements. 54 * 55 * @param name the name of the metric. 56 * @param description the description of the metric. 57 * @param unit the unit of the metric. 58 * @param labelKeys the list of the label keys. 59 * @throws NullPointerException if {@code labelKeys} is null OR any element of {@code labelKeys} 60 * is null OR {@code name}, {@code description}, {@code unit} is null. 61 * @throws IllegalArgumentException if different metric with the same name already registered. 62 * @since 0.17 63 */ 64 @ExperimentalApi addDoubleGauge( String name, String description, String unit, List<LabelKey> labelKeys)65 public abstract DoubleGauge addDoubleGauge( 66 String name, String description, String unit, List<LabelKey> labelKeys); 67 68 /** 69 * Builds a new derived long gauge to be added to the registry. This is more convenient form when 70 * you want to define a gauge by executing a {@link ToLongFunction} on an object. 71 * 72 * @param name the name of the metric. 73 * @param description the description of the metric. 74 * @param unit the unit of the metric. 75 * @param labelKeys the list of the label keys. 76 * @throws NullPointerException if {@code labelKeys} is null OR any element of {@code labelKeys} 77 * is null OR {@code name}, {@code description}, {@code unit} is null. 78 * @throws IllegalArgumentException if different metric with the same name already registered. 79 * @since 0.17 80 */ 81 @ExperimentalApi addDerivedLongGauge( String name, String description, String unit, List<LabelKey> labelKeys)82 public abstract DerivedLongGauge addDerivedLongGauge( 83 String name, String description, String unit, List<LabelKey> labelKeys); 84 85 /** 86 * Builds a new derived double gauge to be added to the registry. This is more convenient form 87 * when you want to define a gauge by executing a {@link ToDoubleFunction} on an object. 88 * 89 * @param name the name of the metric. 90 * @param description the description of the metric. 91 * @param unit the unit of the metric. 92 * @param labelKeys the list of the label keys. 93 * @throws NullPointerException if {@code labelKeys} is null OR any element of {@code labelKeys} 94 * is null OR {@code name}, {@code description}, {@code unit} is null. 95 * @throws IllegalArgumentException if different metric with the same name already registered. 96 * @since 0.17 97 */ 98 @ExperimentalApi addDerivedDoubleGauge( String name, String description, String unit, List<LabelKey> labelKeys)99 public abstract DerivedDoubleGauge addDerivedDoubleGauge( 100 String name, String description, String unit, List<LabelKey> labelKeys); 101 newNoopMetricRegistry()102 static MetricRegistry newNoopMetricRegistry() { 103 return new NoopMetricRegistry(); 104 } 105 106 private static final class NoopMetricRegistry extends MetricRegistry { 107 108 @Override addLongGauge( String name, String description, String unit, List<LabelKey> labelKeys)109 public LongGauge addLongGauge( 110 String name, String description, String unit, List<LabelKey> labelKeys) { 111 Utils.checkListElementNotNull( 112 Utils.checkNotNull(labelKeys, "labelKeys"), "labelKey element should not be null."); 113 return LongGauge.newNoopLongGauge( 114 Utils.checkNotNull(name, "name"), 115 Utils.checkNotNull(description, "description"), 116 Utils.checkNotNull(unit, "unit"), 117 labelKeys); 118 } 119 120 @Override addDoubleGauge( String name, String description, String unit, List<LabelKey> labelKeys)121 public DoubleGauge addDoubleGauge( 122 String name, String description, String unit, List<LabelKey> labelKeys) { 123 Utils.checkListElementNotNull( 124 Utils.checkNotNull(labelKeys, "labelKeys"), "labelKey element should not be null."); 125 return DoubleGauge.newNoopDoubleGauge( 126 Utils.checkNotNull(name, "name"), 127 Utils.checkNotNull(description, "description"), 128 Utils.checkNotNull(unit, "unit"), 129 labelKeys); 130 } 131 132 @Override addDerivedLongGauge( String name, String description, String unit, List<LabelKey> labelKeys)133 public DerivedLongGauge addDerivedLongGauge( 134 String name, String description, String unit, List<LabelKey> labelKeys) { 135 Utils.checkListElementNotNull( 136 Utils.checkNotNull(labelKeys, "labelKeys"), "labelKey element should not be null."); 137 return DerivedLongGauge.newNoopDerivedLongGauge( 138 Utils.checkNotNull(name, "name"), 139 Utils.checkNotNull(description, "description"), 140 Utils.checkNotNull(unit, "unit"), 141 labelKeys); 142 } 143 144 @Override addDerivedDoubleGauge( String name, String description, String unit, List<LabelKey> labelKeys)145 public DerivedDoubleGauge addDerivedDoubleGauge( 146 String name, String description, String unit, List<LabelKey> labelKeys) { 147 Utils.checkListElementNotNull( 148 Utils.checkNotNull(labelKeys, "labelKeys"), "labelKey element should not be null."); 149 return DerivedDoubleGauge.newNoopDerivedDoubleGauge( 150 Utils.checkNotNull(name, "name"), 151 Utils.checkNotNull(description, "description"), 152 Utils.checkNotNull(unit, "unit"), 153 labelKeys); 154 } 155 } 156 } 157