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