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