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;
18 
19 import java.util.List;
20 import javax.annotation.Nullable;
21 
22 /**
23  * Sampler is used to make decisions on {@link Span} sampling.
24  *
25  * @since 0.5
26  */
27 public abstract class Sampler {
28   /**
29    * Called during {@link Span} creation to make a sampling decision.
30    *
31    * @param parentContext the parent span's {@link SpanContext}. {@code null} if this is a root
32    *     span.
33    * @param hasRemoteParent {@code true} if the parent {@code Span} is remote. {@code null} if this
34    *     is a root span.
35    * @param traceId the {@link TraceId} for the new {@code Span}. This will be identical to that in
36    *     the parentContext, unless this is a root span.
37    * @param spanId the {@link SpanId} for the new {@code Span}.
38    * @param name the name of the new {@code Span}.
39    * @param parentLinks the parentLinks associated with the new {@code Span}.
40    * @return {@code true} if the {@code Span} is sampled.
41    * @since 0.5
42    */
shouldSample( @ullable SpanContext parentContext, @Nullable Boolean hasRemoteParent, TraceId traceId, SpanId spanId, String name, List<Span> parentLinks)43   public abstract boolean shouldSample(
44       @Nullable SpanContext parentContext,
45       @Nullable Boolean hasRemoteParent,
46       TraceId traceId,
47       SpanId spanId,
48       String name,
49       List<Span> parentLinks);
50 
51   /**
52    * Returns the description of this {@code Sampler}. This may be displayed on debug pages or in the
53    * logs.
54    *
55    * <p>Example: "ProbabilitySampler{0.000100}"
56    *
57    * @return the description of this {@code Sampler}.
58    * @since 0.6
59    */
getDescription()60   public abstract String getDescription();
61 }
62