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.tags; 18 19 import com.google.auto.value.AutoValue; 20 import javax.annotation.concurrent.Immutable; 21 22 /** 23 * {@link TagMetadata} contains properties associated with a {@link Tag}. 24 * 25 * <p>For now only the property {@link TagTtl} is defined. In future, additional properties may be 26 * added to address specific situations. 27 * 28 * @since 0.20 29 */ 30 @Immutable 31 @AutoValue 32 public abstract class TagMetadata { 33 TagMetadata()34 TagMetadata() {} 35 36 /** 37 * Creates a {@link TagMetadata} with the given {@link TagTtl}. 38 * 39 * @param tagTtl TTL of a {@code Tag}. 40 * @return a {@code TagMetadata}. 41 * @since 0.20 42 */ create(TagTtl tagTtl)43 public static TagMetadata create(TagTtl tagTtl) { 44 return new AutoValue_TagMetadata(tagTtl); 45 } 46 47 /** 48 * Returns the {@link TagTtl} of this {@link TagMetadata}. 49 * 50 * @return the {@code TagTtl}. 51 * @since 0.20 52 */ getTagTtl()53 public abstract TagTtl getTagTtl(); 54 55 /** 56 * {@link TagTtl} is an integer that represents number of hops a tag can propagate. 57 * 58 * <p>Anytime a sender serializes a tag, sends it over the wire and receiver deserializes the tag 59 * then the tag is considered to have travelled one hop. 60 * 61 * <p>There could be one or more proxy(ies) between sender and receiver. Proxies are treated as 62 * transparent entities and they are not counted as hops. 63 * 64 * <p>For now, only special values of {@link TagTtl} are supported. 65 * 66 * @since 0.20 67 */ 68 public enum TagTtl { 69 70 /** 71 * A {@link Tag} with {@link TagTtl#NO_PROPAGATION} is considered to have local scope and is 72 * used within the process where it's created. 73 * 74 * @since 0.20 75 */ 76 NO_PROPAGATION(0), 77 78 /** 79 * A {@link Tag} with {@link TagTtl#UNLIMITED_PROPAGATION} can propagate unlimited hops. 80 * 81 * <p>However, it is still subject to outgoing and incoming (on remote side) filter criteria. 82 * 83 * <p>{@link TagTtl#UNLIMITED_PROPAGATION} is typical used to track a request, which may be 84 * processed across multiple entities. 85 * 86 * @since 0.20 87 */ 88 UNLIMITED_PROPAGATION(-1); 89 90 private final int hops; 91 TagTtl(int hops)92 private TagTtl(int hops) { 93 this.hops = hops; 94 } 95 } 96 } 97