1 /* 2 * Copyright 2017, 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.stats; 18 19 import io.opencensus.internal.Utils; 20 import io.opencensus.stats.Measure.MeasureDouble; 21 import io.opencensus.stats.Measure.MeasureLong; 22 import io.opencensus.tags.TagContext; 23 import javax.annotation.concurrent.NotThreadSafe; 24 25 /** 26 * A map from {@link Measure}s to measured values to be recorded at the same time. 27 * 28 * @since 0.8 29 */ 30 @NotThreadSafe 31 public abstract class MeasureMap { 32 33 /** 34 * Associates the {@link MeasureDouble} with the given value. Subsequent updates to the same 35 * {@link MeasureDouble} will overwrite the previous value. 36 * 37 * @param measure the {@link MeasureDouble} 38 * @param value the value to be associated with {@code measure} 39 * @return this 40 * @since 0.8 41 */ put(MeasureDouble measure, double value)42 public abstract MeasureMap put(MeasureDouble measure, double value); 43 44 /** 45 * Associates the {@link MeasureLong} with the given value. Subsequent updates to the same {@link 46 * MeasureLong} will overwrite the previous value. 47 * 48 * @param measure the {@link MeasureLong} 49 * @param value the value to be associated with {@code measure} 50 * @return this 51 * @since 0.8 52 */ put(MeasureLong measure, long value)53 public abstract MeasureMap put(MeasureLong measure, long value); 54 55 /** 56 * Associate the contextual information of an {@code Exemplar} to this {@link MeasureMap}. 57 * Contextual information is represented as {@code String} key-value pairs. 58 * 59 * <p>If this method is called multiple times with the same key, only the last value will be kept. 60 * 61 * @param key the key of contextual information of an {@code Exemplar}. 62 * @param value the string representation of contextual information of an {@code Exemplar}. 63 * @return this 64 * @since 0.16 65 */ 66 // TODO(songya): make this method abstract in the 0.17 release. putAttachment(String key, String value)67 public MeasureMap putAttachment(String key, String value) { 68 // Provides a default no-op implementation to avoid breaking other existing sub-classes. 69 Utils.checkNotNull(key, "key"); 70 Utils.checkNotNull(value, "value"); 71 return this; 72 } 73 74 /** 75 * Records all of the measures at the same time, with the current {@link TagContext}. 76 * 77 * <p>This method records all of the stats in the {@code MeasureMap} every time it is called. 78 * 79 * @since 0.8 80 */ record()81 public abstract void record(); 82 83 /** 84 * Records all of the measures at the same time, with an explicit {@link TagContext}. 85 * 86 * <p>This method records all of the stats in the {@code MeasureMap} every time it is called. 87 * 88 * @param tags the tags associated with the measurements. 89 * @since 0.8 90 */ record(TagContext tags)91 public abstract void record(TagContext tags); 92 } 93