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.tags; 18 19 import io.opencensus.common.Scope; 20 import io.opencensus.tags.TagMetadata.TagTtl; 21 22 /** 23 * Builder for the {@link TagContext} class. 24 * 25 * @since 0.8 26 */ 27 public abstract class TagContextBuilder { 28 29 private static final TagMetadata METADATA_NO_PROPAGATION = 30 TagMetadata.create(TagTtl.NO_PROPAGATION); 31 private static final TagMetadata METADATA_UNLIMITED_PROPAGATION = 32 TagMetadata.create(TagTtl.UNLIMITED_PROPAGATION); 33 34 /** 35 * Adds the key/value pair regardless of whether the key is present. 36 * 37 * <p>For backwards-compatibility this method still produces propagating {@link Tag}s. 38 * 39 * <p>Equivalent to calling {@code put(key, value, 40 * TagMetadata.create(TagTtl.UNLIMITED_PROPAGATION))}. 41 * 42 * @param key the {@code TagKey} which will be set. 43 * @param value the {@code TagValue} to set for the given key. 44 * @return this 45 * @since 0.8 46 * @deprecated in favor of {@link #put(TagKey, TagValue, TagMetadata)}, or {@link 47 * #putLocal(TagKey, TagValue)} if you only want in-process tags. 48 */ 49 @Deprecated put(TagKey key, TagValue value)50 public abstract TagContextBuilder put(TagKey key, TagValue value); 51 52 /** 53 * Adds the key/value pair and metadata regardless of whether the key is present. 54 * 55 * @param key the {@code TagKey} which will be set. 56 * @param value the {@code TagValue} to set for the given key. 57 * @param tagMetadata the {@code TagMetadata} associated with this {@link Tag}. 58 * @return this 59 * @since 0.20 60 */ put(TagKey key, TagValue value, TagMetadata tagMetadata)61 public TagContextBuilder put(TagKey key, TagValue value, TagMetadata tagMetadata) { 62 @SuppressWarnings("deprecation") 63 TagContextBuilder builder = put(key, value); 64 return builder; 65 } 66 67 /** 68 * Adds a non-propagating tag to this {@code TagContextBuilder}. 69 * 70 * <p>This is equivalent to calling {@code put(key, value, 71 * TagMetadata.create(TagTtl.NO_PROPAGATION))}. 72 * 73 * @param key the {@code TagKey} which will be set. 74 * @param value the {@code TagValue} to set for the given key. 75 * @return this 76 * @since 0.21 77 */ putLocal(TagKey key, TagValue value)78 public final TagContextBuilder putLocal(TagKey key, TagValue value) { 79 return put(key, value, METADATA_NO_PROPAGATION); 80 } 81 82 /** 83 * Adds an unlimited propagating tag to this {@code TagContextBuilder}. 84 * 85 * <p>This is equivalent to calling {@code put(key, value, 86 * TagMetadata.create(TagTtl.METADATA_UNLIMITED_PROPAGATION))}. 87 * 88 * <p>Only call this method if you want propagating tags. If you want tags for breaking down 89 * metrics, or there are sensitive messages in your tags, use {@link #putLocal(TagKey, TagValue)} 90 * instead. 91 * 92 * @param key the {@code TagKey} which will be set. 93 * @param value the {@code TagValue} to set for the given key. 94 * @return this 95 * @since 0.21 96 */ putPropagating(TagKey key, TagValue value)97 public final TagContextBuilder putPropagating(TagKey key, TagValue value) { 98 return put(key, value, METADATA_UNLIMITED_PROPAGATION); 99 } 100 101 /** 102 * Removes the key if it exists. 103 * 104 * @param key the {@code TagKey} which will be removed. 105 * @return this 106 * @since 0.8 107 */ remove(TagKey key)108 public abstract TagContextBuilder remove(TagKey key); 109 110 /** 111 * Creates a {@code TagContext} from this builder. 112 * 113 * @return a {@code TagContext} with the same tags as this builder. 114 * @since 0.8 115 */ build()116 public abstract TagContext build(); 117 118 /** 119 * Enters the scope of code where the {@link TagContext} created from this builder is in the 120 * current context and returns an object that represents that scope. The scope is exited when the 121 * returned object is closed. 122 * 123 * @return an object that defines a scope where the {@code TagContext} created from this builder 124 * is set to the current context. 125 * @since 0.8 126 */ buildScoped()127 public abstract Scope buildScoped(); 128 } 129