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.data; 18 19 import static io.opencensus.internal.Utils.checkNotNull; 20 21 import com.google.auto.value.AutoValue; 22 import io.opencensus.common.Timestamp; 23 import java.util.Collections; 24 import java.util.HashMap; 25 import java.util.Map; 26 import java.util.Map.Entry; 27 import javax.annotation.concurrent.Immutable; 28 29 /** 30 * An example point that may be used to annotate aggregated distribution values, associated with a 31 * histogram bucket. 32 * 33 * @since 0.20 34 */ 35 @Immutable 36 @AutoValue 37 public abstract class Exemplar { 38 Exemplar()39 Exemplar() {} 40 41 /** 42 * Returns value of the {@link Exemplar} point. 43 * 44 * @return value of the {@code Exemplar} point. 45 * @since 0.20 46 */ getValue()47 public abstract double getValue(); 48 49 /** 50 * Returns the time that this {@link Exemplar}'s value was recorded. 51 * 52 * @return the time that this {@code Exemplar}'s value was recorded. 53 * @since 0.20 54 */ getTimestamp()55 public abstract Timestamp getTimestamp(); 56 57 /** 58 * Returns the contextual information about the example value. 59 * 60 * @return the contextual information about the example value. 61 * @since 0.20 62 */ getAttachments()63 public abstract Map<String, AttachmentValue> getAttachments(); 64 65 /** 66 * Creates an {@link Exemplar}. 67 * 68 * @param value value of the {@link Exemplar} point. 69 * @param timestamp the time that this {@code Exemplar}'s value was recorded. 70 * @param attachments the contextual information about the example value. 71 * @return an {@code Exemplar}. 72 * @since 0.20 73 */ create( double value, Timestamp timestamp, Map<String, AttachmentValue> attachments)74 public static Exemplar create( 75 double value, Timestamp timestamp, Map<String, AttachmentValue> attachments) { 76 checkNotNull(attachments, "attachments"); 77 Map<String, AttachmentValue> attachmentsCopy = 78 Collections.unmodifiableMap(new HashMap<String, AttachmentValue>(attachments)); 79 for (Entry<String, AttachmentValue> entry : attachmentsCopy.entrySet()) { 80 checkNotNull(entry.getKey(), "key of attachments"); 81 checkNotNull(entry.getValue(), "value of attachments"); 82 } 83 return new AutoValue_Exemplar(value, timestamp, attachmentsCopy); 84 } 85 } 86