1 /* 2 * Copyright 2019, 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 com.google.auto.value.AutoValue; 20 import io.opencensus.internal.Utils; 21 import java.util.ArrayList; 22 import java.util.Collections; 23 import java.util.HashSet; 24 import java.util.LinkedHashMap; 25 import java.util.List; 26 import java.util.Map; 27 import javax.annotation.concurrent.Immutable; 28 29 /** 30 * Options for every metric added to the {@link MetricRegistry}. 31 * 32 * @since 0.20 33 */ 34 @Immutable 35 @AutoValue 36 public abstract class MetricOptions { 37 38 /** 39 * Returns the description of the Metric. 40 * 41 * <p>Default value is {@code ""}. 42 * 43 * @return the description of the Metric. 44 * @since 0.20 45 */ getDescription()46 public abstract String getDescription(); 47 48 /** 49 * Returns the unit of the Metric. 50 * 51 * <p>Default value is {@code "1"}. 52 * 53 * @return the unit of the Metric. 54 * @since 0.20 55 */ getUnit()56 public abstract String getUnit(); 57 58 /** 59 * Returns the list of label keys for the Metric. 60 * 61 * <p>Default value is {@link Collections#emptyList()}. 62 * 63 * @return the list of label keys for the Metric. 64 * @since 0.20 65 */ getLabelKeys()66 public abstract List<LabelKey> getLabelKeys(); 67 68 /** 69 * Returns the map of constant labels (they will be added to all the TimeSeries) for the Metric. 70 * 71 * <p>Default value is {@link Collections#emptyMap()}. 72 * 73 * @return the map of constant labels for the Metric. 74 * @since 0.21 75 */ getConstantLabels()76 public abstract Map<LabelKey, LabelValue> getConstantLabels(); 77 78 /** 79 * Returns a new {@link Builder} with default options. 80 * 81 * @return a new {@code Builder} with default options. 82 * @since 0.20.0 83 */ builder()84 public static Builder builder() { 85 return new AutoValue_MetricOptions.Builder() 86 .setDescription("") 87 .setUnit("1") 88 .setLabelKeys(Collections.<LabelKey>emptyList()) 89 .setConstantLabels(Collections.<LabelKey, LabelValue>emptyMap()); 90 } 91 92 /** 93 * Builder for {@link MetricOptions}. 94 * 95 * @since 0.20 96 */ 97 @AutoValue.Builder 98 public abstract static class Builder { 99 100 /** 101 * Sets the description of the Metric. 102 * 103 * @param description the description of the Metric. 104 * @return this. 105 * @since 0.20 106 */ setDescription(String description)107 public abstract Builder setDescription(String description); 108 109 /** 110 * Sets the unit of the Metric. 111 * 112 * @param unit the unit of the Metric. 113 * @return this. 114 * @since 0.20 115 */ setUnit(String unit)116 public abstract Builder setUnit(String unit); 117 118 /** 119 * Sets the list of label keys for the Metric. 120 * 121 * @param labelKeys the list of label keys for the Metric. 122 * @return this. 123 * @since 0.20 124 */ setLabelKeys(List<LabelKey> labelKeys)125 public abstract Builder setLabelKeys(List<LabelKey> labelKeys); 126 127 /** 128 * Sets the map of constant labels (they will be added to all the TimeSeries) for the Metric. 129 * 130 * @param constantLabels the map of constant labels for the Metric. 131 * @return this. 132 * @since 0.21 133 */ setConstantLabels(Map<LabelKey, LabelValue> constantLabels)134 public abstract Builder setConstantLabels(Map<LabelKey, LabelValue> constantLabels); 135 getConstantLabels()136 abstract Map<LabelKey, LabelValue> getConstantLabels(); 137 getLabelKeys()138 abstract List<LabelKey> getLabelKeys(); 139 autoBuild()140 abstract MetricOptions autoBuild(); 141 142 /** 143 * Builds and returns a {@code MetricOptions} with the desired options. 144 * 145 * @return a {@code MetricOptions} with the desired options. 146 * @since 0.20 147 * @throws NullPointerException if {@code description}, OR {@code unit} is null, OR {@code 148 * labelKeys} is null OR any element of {@code labelKeys} is null, OR OR {@code 149 * constantLabels} is null OR any element of {@code constantLabels} is null. 150 * @throws IllegalArgumentException if any {@code LabelKey} from the {@code labelKeys} is in the 151 * {@code constantLabels}. 152 */ build()153 public MetricOptions build() { 154 setLabelKeys(Collections.unmodifiableList(new ArrayList<LabelKey>(getLabelKeys()))); 155 setConstantLabels( 156 Collections.unmodifiableMap( 157 new LinkedHashMap<LabelKey, LabelValue>(getConstantLabels()))); 158 MetricOptions options = autoBuild(); 159 Utils.checkListElementNotNull(options.getLabelKeys(), "labelKeys elements"); 160 Utils.checkMapElementNotNull(options.getConstantLabels(), "constantLabels elements"); 161 162 HashSet<String> labelKeyNamesMap = new HashSet<String>(); 163 for (LabelKey labelKey : options.getLabelKeys()) { 164 if (labelKeyNamesMap.contains(labelKey.getKey())) { 165 throw new IllegalArgumentException("Invalid LabelKey in labelKeys"); 166 } 167 labelKeyNamesMap.add(labelKey.getKey()); 168 } 169 for (Map.Entry<LabelKey, LabelValue> constantLabel : options.getConstantLabels().entrySet()) { 170 if (labelKeyNamesMap.contains(constantLabel.getKey().getKey())) { 171 throw new IllegalArgumentException("Invalid LabelKey in constantLabels"); 172 } 173 labelKeyNamesMap.add(constantLabel.getKey().getKey()); 174 } 175 return options; 176 } 177 Builder()178 Builder() {} 179 } 180 MetricOptions()181 MetricOptions() {} 182 } 183