Return sampler decision with tags from Sampler (#339)

* Make sampler return sampling decision

Signed-off-by: Pavol Loffay <ploffay@redhat.com>

* Fix review comments

Signed-off-by: Pavol Loffay <ploffay@redhat.com>

* Use package visibility

Signed-off-by: Pavol Loffay <ploffay@redhat.com>

* Define as final

Signed-off-by: Pavol Loffay <ploffay@redhat.com>

* Rename do decision and fix javadoc

Signed-off-by: Pavol Loffay <ploffay@redhat.com>

* Make it package private

Signed-off-by: Pavol Loffay <ploffay@redhat.com>

* Rename to simpledecision

Signed-off-by: Pavol Loffay <ploffay@redhat.com>

api/src/main/java/io/opentelemetry/trace/Sampler.java

@@ -17,6 +17,7 @@
 package io.opentelemetry.trace;
 
 import java.util.List;
+import java.util.Map;
 import javax.annotation.Nullable;
 
 /**
@@ -37,10 +38,10 @@ public interface Sampler {
    * @param spanId the {@link SpanId} for the new {@code Span}.
    * @param name the name of the new {@code Span}.
    * @param parentLinks the parentLinks associated with the new {@code Span}.
-   * @return {@code true} if the {@code Span} is sampled.
+   * @return sampling decision whether span should be sampled or not.
    * @since 0.1.0
    */
-  boolean shouldSample(
+  Decision shouldSample(
       @Nullable SpanContext parentContext,
       @Nullable Boolean hasRemoteParent,
       TraceId traceId,
@@ -58,4 +59,30 @@ public interface Sampler {
    * @since 0.1.0
    */
   String getDescription();
+
+  /**
+   * Sampling decision returned by {@link Sampler#shouldSample(SpanContext, Boolean, TraceId,
+   * SpanId, String, List)}.
+   *
+   * @since 0.1.0
+   */
+  interface Decision {
+
+    /**
+     * Return sampling decision whether span should be sampled or not.
+     *
+     * @return sampling decision.
+     * @since 0.1.0
+     */
+    boolean isSampled();
+
+    /**
+     * Return tags which will be attached to the span.
+     *
+     * @return attributes added to span. These attributes should be added to the span only for root
+     *     span or when sampling decision {@link #isSampled()} changes from false to true.
+     * @since 0.1.0
+     */
+    Map<String, AttributeValue> attributes();
+  }
 }

api/src/main/java/io/opentelemetry/trace/samplers/AlwaysSampleSampler.java

@@ -28,19 +28,20 @@ import javax.annotation.concurrent.Immutable;
 /** Sampler that always makes a "yes" decision on {@link Span} sampling. */
 @Immutable
 final class AlwaysSampleSampler implements Sampler {
+  private static final Decision DECISION = new SimpleDecision(true);
 
   AlwaysSampleSampler() {}
 
   // Returns always makes a "yes" decision on {@link Span} sampling.
   @Override
-  public boolean shouldSample(
+  public Decision shouldSample(
       @Nullable SpanContext parentContext,
       @Nullable Boolean hasRemoteParent,
       TraceId traceId,
       SpanId spanId,
       String name,
       List<Span> parentLinks) {
-    return true;
+    return DECISION;
   }
 
   @Override

api/src/main/java/io/opentelemetry/trace/samplers/NeverSampleSampler.java

@@ -28,19 +28,20 @@ import javax.annotation.concurrent.Immutable;
 /** Sampler that always makes a "no" decision on {@link Span} sampling. */
 @Immutable
 final class NeverSampleSampler implements Sampler {
+  private static final Decision DECISION = new SimpleDecision(false);
 
   NeverSampleSampler() {}
 
   // Returns always makes a "no" decision on {@link Span} sampling.
   @Override
-  public boolean shouldSample(
+  public Decision shouldSample(
       @Nullable SpanContext parentContext,
       @Nullable Boolean hasRemoteParent,
       TraceId traceId,
       SpanId spanId,
       String name,
       List<Span> parentLinks) {
-    return false;
+    return DECISION;
   }
 
   @Override

api/src/main/java/io/opentelemetry/trace/samplers/SimpleDecision.java

@@ -0,0 +1,47 @@
+/*
+ * Copyright 2019, OpenTelemetry Authors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package io.opentelemetry.trace.samplers;
+
+import io.opentelemetry.trace.AttributeValue;
+import io.opentelemetry.trace.Sampler.Decision;
+import java.util.Collections;
+import java.util.Map;
+
+/** Sampling decision without attributes. */
+final class SimpleDecision implements Decision {
+
+  private final boolean decision;
+
+  /**
+   * Creates sampling decision without attributes.
+   *
+   * @param decision sampling decision
+   */
+  SimpleDecision(boolean decision) {
+    this.decision = decision;
+  }
+
+  @Override
+  public boolean isSampled() {
+    return decision;
+  }
+
+  @Override
+  public Map<String, AttributeValue> attributes() {
+    return Collections.emptyMap();
+  }
+}

api/src/test/java/io/opentelemetry/trace/samplers/SamplersTest.java

@@ -57,7 +57,8 @@ public class SamplersTest {
                     traceId,
                     spanId,
                     "Another name",
-                    Collections.<Span>emptyList()))
+                    Collections.<Span>emptyList())
+                .isSampled())
         .isTrue();
     // Not sampled parent.
     Truth.assertThat(
@@ -68,7 +69,8 @@ public class SamplersTest {
                     traceId,
                     spanId,
                     "Yet another name",
-                    Collections.<Span>emptyList()))
+                    Collections.<Span>emptyList())
+                .isSampled())
         .isTrue();
   }
 
@@ -88,7 +90,8 @@ public class SamplersTest {
                     traceId,
                     spanId,
                     "bar",
-                    Collections.<Span>emptyList()))
+                    Collections.<Span>emptyList())
+                .isSampled())
         .isFalse();
     // Not sampled parent.
     Truth.assertThat(
@@ -99,7 +102,8 @@ public class SamplersTest {
                     traceId,
                     spanId,
                     "quux",
-                    Collections.<Span>emptyList()))
+                    Collections.<Span>emptyList())
+                .isSampled())
         .isFalse();
   }