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.trace.config; 18 19 import com.google.auto.value.AutoValue; 20 import io.opencensus.internal.Utils; 21 import io.opencensus.trace.Annotation; 22 import io.opencensus.trace.Link; 23 import io.opencensus.trace.MessageEvent; 24 import io.opencensus.trace.Sampler; 25 import io.opencensus.trace.Span; 26 import io.opencensus.trace.samplers.Samplers; 27 import javax.annotation.concurrent.Immutable; 28 29 /** 30 * Class that holds global trace parameters. 31 * 32 * @since 0.5 33 */ 34 @AutoValue 35 @Immutable 36 public abstract class TraceParams { 37 // These values are the default values for all the global parameters. 38 private static final double DEFAULT_PROBABILITY = 1e-4; 39 private static final Sampler DEFAULT_SAMPLER = Samplers.probabilitySampler(DEFAULT_PROBABILITY); 40 private static final int DEFAULT_SPAN_MAX_NUM_ATTRIBUTES = 32; 41 private static final int DEFAULT_SPAN_MAX_NUM_ANNOTATIONS = 32; 42 private static final int DEFAULT_SPAN_MAX_NUM_MESSAGE_EVENTS = 128; 43 private static final int DEFAULT_SPAN_MAX_NUM_LINKS = 32; 44 45 /** 46 * Default {@code TraceParams}. 47 * 48 * @since 0.5 49 */ 50 public static final TraceParams DEFAULT = 51 TraceParams.builder() 52 .setSampler(DEFAULT_SAMPLER) 53 .setMaxNumberOfAttributes(DEFAULT_SPAN_MAX_NUM_ATTRIBUTES) 54 .setMaxNumberOfAnnotations(DEFAULT_SPAN_MAX_NUM_ANNOTATIONS) 55 .setMaxNumberOfMessageEvents(DEFAULT_SPAN_MAX_NUM_MESSAGE_EVENTS) 56 .setMaxNumberOfLinks(DEFAULT_SPAN_MAX_NUM_LINKS) 57 .build(); 58 59 /** 60 * Returns the global default {@code Sampler}. Used if no {@code Sampler} is provided in {@link 61 * io.opencensus.trace.SpanBuilder#setSampler(Sampler)}. 62 * 63 * @return the global default {@code Sampler}. 64 * @since 0.5 65 */ getSampler()66 public abstract Sampler getSampler(); 67 68 /** 69 * Returns the global default max number of attributes per {@link Span}. 70 * 71 * @return the global default max number of attributes per {@link Span}. 72 * @since 0.5 73 */ getMaxNumberOfAttributes()74 public abstract int getMaxNumberOfAttributes(); 75 76 /** 77 * Returns the global default max number of {@link Annotation} events per {@link Span}. 78 * 79 * @return the global default max number of {@code Annotation} events per {@code Span}. 80 * @since 0.5 81 */ getMaxNumberOfAnnotations()82 public abstract int getMaxNumberOfAnnotations(); 83 84 /** 85 * Returns the global default max number of {@link MessageEvent} events per {@link Span}. 86 * 87 * @return the global default max number of {@code MessageEvent} events per {@code Span}. 88 * @since 0.12 89 */ getMaxNumberOfMessageEvents()90 public abstract int getMaxNumberOfMessageEvents(); 91 92 /** 93 * Returns the global default max number of {@link io.opencensus.trace.NetworkEvent} events per 94 * {@link Span}. 95 * 96 * @return the global default max number of {@code NetworkEvent} events per {@code Span}. 97 * @deprecated Use {@link getMaxNumberOfMessageEvents}. 98 * @since 0.5 99 */ 100 @Deprecated getMaxNumberOfNetworkEvents()101 public int getMaxNumberOfNetworkEvents() { 102 return getMaxNumberOfMessageEvents(); 103 } 104 105 /** 106 * Returns the global default max number of {@link Link} entries per {@link Span}. 107 * 108 * @return the global default max number of {@code Link} entries per {@code Span}. 109 * @since 0.5 110 */ getMaxNumberOfLinks()111 public abstract int getMaxNumberOfLinks(); 112 builder()113 private static Builder builder() { 114 return new AutoValue_TraceParams.Builder(); 115 } 116 117 /** 118 * Returns a {@link Builder} initialized to the same property values as the current instance. 119 * 120 * @return a {@link Builder} initialized to the same property values as the current instance. 121 * @since 0.5 122 */ toBuilder()123 public abstract Builder toBuilder(); 124 125 /** 126 * A {@code Builder} class for {@link TraceParams}. 127 * 128 * @since 0.5 129 */ 130 @AutoValue.Builder 131 public abstract static class Builder { 132 133 /** 134 * Sets the global default {@code Sampler}. It must be not {@code null} otherwise {@link 135 * #build()} will throw an exception. 136 * 137 * @param sampler the global default {@code Sampler}. 138 * @return this. 139 * @since 0.5 140 */ setSampler(Sampler sampler)141 public abstract Builder setSampler(Sampler sampler); 142 143 /** 144 * Sets the global default max number of attributes per {@link Span}. 145 * 146 * @param maxNumberOfAttributes the global default max number of attributes per {@link Span}. It 147 * must be positive otherwise {@link #build()} will throw an exception. 148 * @return this. 149 * @since 0.5 150 */ setMaxNumberOfAttributes(int maxNumberOfAttributes)151 public abstract Builder setMaxNumberOfAttributes(int maxNumberOfAttributes); 152 153 /** 154 * Sets the global default max number of {@link Annotation} events per {@link Span}. 155 * 156 * @param maxNumberOfAnnotations the global default max number of {@link Annotation} events per 157 * {@link Span}. It must be positive otherwise {@link #build()} will throw an exception. 158 * @return this. 159 * @since 0.5 160 */ setMaxNumberOfAnnotations(int maxNumberOfAnnotations)161 public abstract Builder setMaxNumberOfAnnotations(int maxNumberOfAnnotations); 162 163 /** 164 * Sets the global default max number of {@link MessageEvent} events per {@link Span}. 165 * 166 * @param maxNumberOfMessageEvents the global default max number of {@link MessageEvent} events 167 * per {@link Span}. It must be positive otherwise {@link #build()} will throw an exception. 168 * @since 0.12 169 * @return this. 170 */ setMaxNumberOfMessageEvents(int maxNumberOfMessageEvents)171 public abstract Builder setMaxNumberOfMessageEvents(int maxNumberOfMessageEvents); 172 173 /** 174 * Sets the global default max number of {@link io.opencensus.trace.NetworkEvent} events per 175 * {@link Span}. 176 * 177 * @param maxNumberOfNetworkEvents the global default max number of {@link 178 * io.opencensus.trace.NetworkEvent} events per {@link Span}. It must be positive otherwise 179 * {@link #build()} will throw an exception. 180 * @return this. 181 * @deprecated Use {@link setMaxNumberOfMessageEvents}. 182 * @since 0.5 183 */ 184 @Deprecated setMaxNumberOfNetworkEvents(int maxNumberOfNetworkEvents)185 public Builder setMaxNumberOfNetworkEvents(int maxNumberOfNetworkEvents) { 186 return setMaxNumberOfMessageEvents(maxNumberOfNetworkEvents); 187 } 188 189 /** 190 * Sets the global default max number of {@link Link} entries per {@link Span}. 191 * 192 * @param maxNumberOfLinks the global default max number of {@link Link} entries per {@link 193 * Span}. It must be positive otherwise {@link #build()} will throw an exception. 194 * @return this. 195 * @since 0.5 196 */ setMaxNumberOfLinks(int maxNumberOfLinks)197 public abstract Builder setMaxNumberOfLinks(int maxNumberOfLinks); 198 autoBuild()199 abstract TraceParams autoBuild(); 200 201 /** 202 * Builds and returns a {@code TraceParams} with the desired values. 203 * 204 * @return a {@code TraceParams} with the desired values. 205 * @throws NullPointerException if the sampler is {@code null}. 206 * @throws IllegalArgumentException if any of the max numbers are not positive. 207 * @since 0.5 208 */ build()209 public TraceParams build() { 210 TraceParams traceParams = autoBuild(); 211 Utils.checkArgument(traceParams.getMaxNumberOfAttributes() > 0, "maxNumberOfAttributes"); 212 Utils.checkArgument(traceParams.getMaxNumberOfAnnotations() > 0, "maxNumberOfAnnotations"); 213 Utils.checkArgument( 214 traceParams.getMaxNumberOfMessageEvents() > 0, "maxNumberOfMessageEvents"); 215 Utils.checkArgument(traceParams.getMaxNumberOfLinks() > 0, "maxNumberOfLinks"); 216 return traceParams; 217 } 218 } 219 } 220