Move Sampler and StartSpanOptions in base. Create a samplers package for all the Sampler implementations. (#347)

24 files changed, 291 insertions, 191 deletions

diff --git a/api/src/main/java/io/opencensus/trace/Samplers.java b/api/src/main/java/io/opencensus/trace/Samplers.java
deleted file mode 100644
index 8d7908ec..00000000
--- a/api/src/main/java/io/opencensus/trace/Samplers.java
+++ /dev/null
@@ -1,168 +0,0 @@
-/*
- * Copyright 2017, Google Inc.
- * 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.opencensus.trace;
-
-import static com.google.common.base.Preconditions.checkArgument;
-
-import com.google.auto.value.AutoValue;
-import io.opencensus.trace.base.SpanId;
-import io.opencensus.trace.base.TraceId;
-import java.util.List;
-import javax.annotation.Nullable;
-import javax.annotation.concurrent.Immutable;
-
-/** Static class to access a set of pre-defined {@link Sampler Samplers}. */
-public final class Samplers {
-  private static final Sampler ALWAYS_SAMPLE = new AlwaysSampleSampler();
-  private static final Sampler NEVER_SAMPLE = new NeverSampleSampler();
-
-  // No instance of this class.
-  private Samplers() {}
-
-  /**
-   * Returns a {@link Sampler} that always makes a "yes" decision on {@link Span} sampling.
-   *
-   * @return a {@code Sampler} that always makes a "yes" decision on {@code Span} sampling.
-   */
-  public static Sampler alwaysSample() {
-    return ALWAYS_SAMPLE;
-  }
-
-  /**
-   * Returns a {@link Sampler} that always makes a "no" decision on {@link Span} sampling.
-   *
-   * @return a {@code Sampler} that always makes a "no" decision on {@code Span} sampling.
-   */
-  public static Sampler neverSample() {
-    return NEVER_SAMPLE;
-  }
-
-  /**
-   * Returns a {@link Sampler} that makes a "yes" decision with a given probability.
-   *
-   * @param probability The desired probability of sampling. Must be within [0.0, 1.0].
-   * @return a {@code Sampler} that makes a "yes" decision with a given probability.
-   * @throws IllegalArgumentException if {@code probability} is out of range
-   */
-  public static Sampler probabilitySampler(double probability) {
-    return ProbabilitySampler.create(probability);
-  }
-
-  @Immutable
-  private static final class AlwaysSampleSampler extends Sampler {
-    private AlwaysSampleSampler() {}
-
-    // Returns always makes a "yes" decision on {@link Span} sampling.
-    @Override
-    protected boolean shouldSample(
-        @Nullable SpanContext parentContext,
-        boolean remoteParent,
-        TraceId traceId,
-        SpanId spanId,
-        String name,
-        List<Span> parentLinks) {
-      return true;
-    }
-
-    @Override
-    public String toString() {
-      return "AlwaysSampleSampler";
-    }
-  }
-
-  @Immutable
-  private static final class NeverSampleSampler extends Sampler {
-    private NeverSampleSampler() {}
-
-    // Returns always makes a "no" decision on {@link Span} sampling.
-    @Override
-    protected boolean shouldSample(
-        @Nullable SpanContext parentContext,
-        boolean remoteParent,
-        TraceId traceId,
-        SpanId spanId,
-        String name,
-        List<Span> parentLinks) {
-      return false;
-    }
-
-    @Override
-    public String toString() {
-      return "NeverSampleSampler";
-    }
-  }
-
-  // We assume the lower 64 bits of the traceId's are randomly distributed around the whole (long)
-  // range. We convert an incoming probability into an upper bound on that value, such that we can
-  // just compare the absolute value of the id and the bound to see if we are within the desired
-  // probability range.  Using the low bits of the traceId also ensures that systems that only use
-  // 64 bit ID's will also work with this sampler.
-  @AutoValue
-  @Immutable
-  abstract static class ProbabilitySampler extends Sampler {
-    ProbabilitySampler() {}
-
-    abstract double getProbability();
-
-    abstract long getIdUpperBound();
-
-    /**
-     * Returns a new {@link ProbabilitySampler}. The probability of sampling a trace is equal to
-     * that of the specified probability.
-     *
-     * @param probability The desired probability of sampling. Must be within [0.0, 1.0].
-     * @return a new {@link ProbabilitySampler}.
-     * @throws IllegalArgumentException if {@code probability} is out of range
-     */
-    private static ProbabilitySampler create(double probability) {
-      checkArgument(
-          probability >= 0.0 && probability <= 1.0, "probability must be in range [0.0, 1.0]");
-      long idUpperBound = 0;
-      // Special case the limits, to avoid any possible issues with lack of precision across
-      // double/long boundaries. For probability == 0.0, we use Long.MIN_VALUE as this guarantees
-      // that we will never sample a trace, even in the case where the id == Long.MIN_VALUE, since
-      // Math.Abs(Long.MIN_VALUE) == Long.MIN_VALUE.
-      if (probability == 0.0) {
-        idUpperBound = Long.MIN_VALUE;
-      } else if (probability == 1.0) {
-        idUpperBound = Long.MAX_VALUE;
-      } else {
-        idUpperBound = (long) (probability * Long.MAX_VALUE);
-      }
-      return new AutoValue_Samplers_ProbabilitySampler(probability, idUpperBound);
-    }
-
-    @Override
-    protected final boolean shouldSample(
-        @Nullable SpanContext parentContext,
-        boolean remoteParent,
-        TraceId traceId,
-        SpanId spanId,
-        String name,
-        @Nullable List<Span> parentLinks) {
-      // Always enable sampling if parent was sampled.
-      if (parentContext != null && parentContext.getTraceOptions().isSampled()) {
-        return true;
-      }
-      // Always sample if we are within probability range. This is true even for child spans (that
-      // may have had a different sampling decision made) to allow for different sampling policies,
-      // and dynamic increases to sampling probabilities for debugging purposes.
-      // Note use of '<' for comparison. This ensures that we never sample for probability == 0.0,
-      // while allowing for a (very) small chance of *not* sampling if the id == Long.MAX_VALUE.
-      // This is considered a reasonable tradeoff for the simplicity/performance requirements (this
-      // code is executed in-line for every Span creation).
-      return Math.abs(traceId.getLowerLong()) < getIdUpperBound();
-    }
-  }
-}
diff --git a/api/src/main/java/io/opencensus/trace/Span.java b/api/src/main/java/io/opencensus/trace/Span.java
index 0a941287..f1661901 100644
--- a/api/src/main/java/io/opencensus/trace/Span.java
+++ b/api/src/main/java/io/opencensus/trace/Span.java
@@ -21,6 +21,7 @@ import io.opencensus.trace.base.AttributeValue;
 import io.opencensus.trace.base.EndSpanOptions;
 import io.opencensus.trace.base.Link;
 import io.opencensus.trace.base.NetworkEvent;
+import io.opencensus.trace.base.StartSpanOptions;
 import java.util.Collections;
 import java.util.EnumSet;
 import java.util.Map;
diff --git a/api/src/main/java/io/opencensus/trace/SpanBuilder.java b/api/src/main/java/io/opencensus/trace/SpanBuilder.java
index b3ad8a5f..782248ba 100644
--- a/api/src/main/java/io/opencensus/trace/SpanBuilder.java
+++ b/api/src/main/java/io/opencensus/trace/SpanBuilder.java
@@ -15,6 +15,8 @@ package io.opencensus.trace;
 
 import io.opencensus.common.NonThrowingCloseable;
 import io.opencensus.trace.base.EndSpanOptions;
+import io.opencensus.trace.base.Sampler;
+import io.opencensus.trace.base.StartSpanOptions;
 import io.opencensus.trace.internal.SpanFactory;
 import java.util.List;
 import javax.annotation.Nullable;
diff --git a/api/src/main/java/io/opencensus/trace/Tracer.java b/api/src/main/java/io/opencensus/trace/Tracer.java
index 64f0ae49..e6172bed 100644
--- a/api/src/main/java/io/opencensus/trace/Tracer.java
+++ b/api/src/main/java/io/opencensus/trace/Tracer.java
@@ -16,6 +16,7 @@ package io.opencensus.trace;
 import static com.google.common.base.Preconditions.checkNotNull;
 
 import io.opencensus.common.NonThrowingCloseable;
+import io.opencensus.trace.base.StartSpanOptions;
 import io.opencensus.trace.internal.SpanFactory;
 import javax.annotation.Nullable;
 
diff --git a/api/src/main/java/io/opencensus/trace/Sampler.java b/api/src/main/java/io/opencensus/trace/base/Sampler.java
index d231f41b..94bd2966 100644
--- a/api/src/main/java/io/opencensus/trace/Sampler.java
+++ b/api/src/main/java/io/opencensus/trace/base/Sampler.java
@@ -11,10 +11,11 @@
  * limitations under the License.
  */
 
-package io.opencensus.trace;
+package io.opencensus.trace.base;
+
+import io.opencensus.trace.Span;
+import io.opencensus.trace.SpanContext;
 
-import io.opencensus.trace.base.SpanId;
-import io.opencensus.trace.base.TraceId;
 import java.util.List;
 import javax.annotation.Nullable;
 
@@ -33,7 +34,7 @@ public abstract class Sampler {
    * @param parentLinks The parentLinks associated with the new {@code Span}.
    * @return {@code true} if the {@code Span} is sampled.
    */
-  protected abstract boolean shouldSample(
+  public abstract boolean shouldSample(
       @Nullable SpanContext parentContext,
       boolean remoteParent,
       TraceId traceId,
diff --git a/api/src/main/java/io/opencensus/trace/StartSpanOptions.java b/api/src/main/java/io/opencensus/trace/base/StartSpanOptions.java
index 9b7ccb65..518f1e60 100644
--- a/api/src/main/java/io/opencensus/trace/StartSpanOptions.java
+++ b/api/src/main/java/io/opencensus/trace/base/StartSpanOptions.java
@@ -11,10 +11,11 @@
  * limitations under the License.
  */
 
-package io.opencensus.trace;
+package io.opencensus.trace.base;
 
 import com.google.auto.value.AutoValue;
 import com.google.common.annotations.VisibleForTesting;
+import io.opencensus.trace.Span;
 import io.opencensus.trace.config.TraceConfig;
 import java.util.ArrayList;
 import java.util.Collections;
@@ -33,7 +34,7 @@ public abstract class StartSpanOptions {
   private static final List<Span> EMPTY_PARENT_LINKS_LIST = Collections.emptyList();
 
   /** The default {@code StartSpanOptions}. */
-  @VisibleForTesting static final StartSpanOptions DEFAULT = builder().build();
+  @VisibleForTesting public static final StartSpanOptions DEFAULT = builder().build();
 
   /**
    * Returns the {@link Sampler} to be used, or {@code null} if default.
diff --git a/api/src/main/java/io/opencensus/trace/config/TraceParams.java b/api/src/main/java/io/opencensus/trace/config/TraceParams.java
index 1f0e093f..74953cfd 100644
--- a/api/src/main/java/io/opencensus/trace/config/TraceParams.java
+++ b/api/src/main/java/io/opencensus/trace/config/TraceParams.java
@@ -16,13 +16,13 @@ package io.opencensus.trace.config;
 import static com.google.common.base.Preconditions.checkArgument;
 
 import com.google.auto.value.AutoValue;
-import io.opencensus.trace.Sampler;
-import io.opencensus.trace.Samplers;
 import io.opencensus.trace.Span;
-import io.opencensus.trace.StartSpanOptions;
 import io.opencensus.trace.base.Annotation;
 import io.opencensus.trace.base.Link;
 import io.opencensus.trace.base.NetworkEvent;
+import io.opencensus.trace.base.Sampler;
+import io.opencensus.trace.base.StartSpanOptions;
+import io.opencensus.trace.samplers.Samplers;
 import javax.annotation.concurrent.Immutable;
 
 /** Class that holds global trace parameters. */
@@ -109,8 +109,8 @@ public abstract class TraceParams {
     /**
      * Sets the global default max number of attributes per {@link Span}.
      *
-     * @param maxNumberOfAttributes the global default max number of attributes per {@link Span}.
-     *     It must be positive otherwise {@link #build()} will throw an exception.
+     * @param maxNumberOfAttributes the global default max number of attributes per {@link Span}. It
+     *     must be positive otherwise {@link #build()} will throw an exception.
      * @return this.
      */
     public abstract Builder setMaxNumberOfAttributes(int maxNumberOfAttributes);
@@ -118,9 +118,8 @@ public abstract class TraceParams {
     /**
      * Sets the global default max number of {@link Annotation} events per {@link Span}.
      *
-     * @param maxNumberOfAnnotations the global default max number of {@link Annotation} events
-     *     per {@link Span}. It must be positive otherwise {@link #build()} will throw an
-     *     exception.
+     * @param maxNumberOfAnnotations the global default max number of {@link Annotation} events per
+     *     {@link Span}. It must be positive otherwise {@link #build()} will throw an exception.
      * @return this.
      */
     public abstract Builder setMaxNumberOfAnnotations(int maxNumberOfAnnotations);
@@ -128,9 +127,8 @@ public abstract class TraceParams {
     /**
      * Sets the global default max number of {@link NetworkEvent} events per {@link Span}.
      *
-     * @param maxNumberOfNetworkEvents the global default max number of {@link NetworkEvent}
-     *     events per {@link Span}. It must be positive otherwise {@link #build()} will throw an
-     *     exception.
+     * @param maxNumberOfNetworkEvents the global default max number of {@link NetworkEvent} events
+     *     per {@link Span}. It must be positive otherwise {@link #build()} will throw an exception.
      * @return this.
      */
     public abstract Builder setMaxNumberOfNetworkEvents(int maxNumberOfNetworkEvents);
diff --git a/api/src/main/java/io/opencensus/trace/internal/SpanFactory.java b/api/src/main/java/io/opencensus/trace/internal/SpanFactory.java
index b93ec865..a0306152 100644
--- a/api/src/main/java/io/opencensus/trace/internal/SpanFactory.java
+++ b/api/src/main/java/io/opencensus/trace/internal/SpanFactory.java
@@ -15,7 +15,7 @@ package io.opencensus.trace.internal;
 
 import io.opencensus.trace.Span;
 import io.opencensus.trace.SpanContext;
-import io.opencensus.trace.StartSpanOptions;
+import io.opencensus.trace.base.StartSpanOptions;
 import javax.annotation.Nullable;
 
 /** Factory class to create and start a {@link Span}. */
diff --git a/api/src/main/java/io/opencensus/trace/samplers/AlwaysSampleSampler.java b/api/src/main/java/io/opencensus/trace/samplers/AlwaysSampleSampler.java
new file mode 100644
index 00000000..f3daed4b
--- /dev/null
+++ b/api/src/main/java/io/opencensus/trace/samplers/AlwaysSampleSampler.java
@@ -0,0 +1,50 @@
+/*
+ * Copyright 2017, Google Inc.
+ * 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.opencensus.trace.samplers;
+
+import io.opencensus.trace.Span;
+import io.opencensus.trace.SpanContext;
+import io.opencensus.trace.base.Sampler;
+import io.opencensus.trace.base.SpanId;
+import io.opencensus.trace.base.TraceId;
+import java.util.List;
+import javax.annotation.Nullable;
+import javax.annotation.concurrent.Immutable;
+
+/**
+ * Sampler that always makes a "yes" decision on {@link Span} sampling.
+ */
+@Immutable
+final class AlwaysSampleSampler extends Sampler {
+
+  AlwaysSampleSampler() {
+  }
+
+  // Returns always makes a "yes" decision on {@link Span} sampling.
+  @Override
+  public boolean shouldSample(
+      @Nullable SpanContext parentContext,
+      boolean remoteParent,
+      TraceId traceId,
+      SpanId spanId,
+      String name,
+      List<Span> parentLinks) {
+    return true;
+  }
+
+  @Override
+  public String toString() {
+    return "AlwaysSampleSampler";
+  }
+}
diff --git a/api/src/main/java/io/opencensus/trace/samplers/NeverSampleSampler.java b/api/src/main/java/io/opencensus/trace/samplers/NeverSampleSampler.java
new file mode 100644
index 00000000..bca64df4
--- /dev/null
+++ b/api/src/main/java/io/opencensus/trace/samplers/NeverSampleSampler.java
@@ -0,0 +1,50 @@
+/*
+ * Copyright 2017, Google Inc.
+ * 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.opencensus.trace.samplers;
+
+import io.opencensus.trace.Span;
+import io.opencensus.trace.SpanContext;
+import io.opencensus.trace.base.Sampler;
+import io.opencensus.trace.base.SpanId;
+import io.opencensus.trace.base.TraceId;
+import java.util.List;
+import javax.annotation.Nullable;
+import javax.annotation.concurrent.Immutable;
+
+/**
+ * Sampler that always makes a "no" decision on {@link Span} sampling.
+ */
+@Immutable
+final class NeverSampleSampler extends Sampler {
+
+  NeverSampleSampler() {
+  }
+
+  // Returns always makes a "no" decision on {@link Span} sampling.
+  @Override
+  public boolean shouldSample(
+      @Nullable SpanContext parentContext,
+      boolean remoteParent,
+      TraceId traceId,
+      SpanId spanId,
+      String name,
+      List<Span> parentLinks) {
+    return false;
+  }
+
+  @Override
+  public String toString() {
+    return "NeverSampleSampler";
+  }
+}
diff --git a/api/src/main/java/io/opencensus/trace/samplers/ProbabilitySampler.java b/api/src/main/java/io/opencensus/trace/samplers/ProbabilitySampler.java
new file mode 100644
index 00000000..c5c9c002
--- /dev/null
+++ b/api/src/main/java/io/opencensus/trace/samplers/ProbabilitySampler.java
@@ -0,0 +1,93 @@
+/*
+ * Copyright 2017, Google Inc.
+ * 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.opencensus.trace.samplers;
+
+import static com.google.common.base.Preconditions.checkArgument;
+
+import com.google.auto.value.AutoValue;
+import io.opencensus.trace.Span;
+import io.opencensus.trace.SpanContext;
+import io.opencensus.trace.base.Sampler;
+import io.opencensus.trace.base.SpanId;
+import io.opencensus.trace.base.TraceId;
+import java.util.List;
+import javax.annotation.Nullable;
+import javax.annotation.concurrent.Immutable;
+
+/**
+ * We assume the lower 64 bits of the traceId's are randomly distributed around the whole (long)
+ * range. We convert an incoming probability into an upper bound on that value, such that we can
+ * just compare the absolute value of the id and the bound to see if we are within the desired
+ * probability range.  Using the low bits of the traceId also ensures that systems that only use
+ * 64 bit ID's will also work with this sampler.
+ */
+@AutoValue
+@Immutable
+abstract class ProbabilitySampler extends Sampler {
+
+  ProbabilitySampler() {
+  }
+
+  abstract double getProbability();
+
+  abstract long getIdUpperBound();
+
+  /**
+   * Returns a new {@link ProbabilitySampler}. The probability of sampling a trace is equal to
+   * that of the specified probability.
+   *
+   * @param probability The desired probability of sampling. Must be within [0.0, 1.0].
+   * @return a new {@link ProbabilitySampler}.
+   * @throws IllegalArgumentException if {@code probability} is out of range
+   */
+  static ProbabilitySampler create(double probability) {
+    checkArgument(
+        probability >= 0.0 && probability <= 1.0, "probability must be in range [0.0, 1.0]");
+    long idUpperBound = 0;
+    // Special case the limits, to avoid any possible issues with lack of precision across
+    // double/long boundaries. For probability == 0.0, we use Long.MIN_VALUE as this guarantees
+    // that we will never sample a trace, even in the case where the id == Long.MIN_VALUE, since
+    // Math.Abs(Long.MIN_VALUE) == Long.MIN_VALUE.
+    if (probability == 0.0) {
+      idUpperBound = Long.MIN_VALUE;
+    } else if (probability == 1.0) {
+      idUpperBound = Long.MAX_VALUE;
+    } else {
+      idUpperBound = (long) (probability * Long.MAX_VALUE);
+    }
+    return new AutoValue_ProbabilitySampler(probability, idUpperBound);
+  }
+
+  @Override
+  public final boolean shouldSample(
+      @Nullable SpanContext parentContext,
+      boolean remoteParent,
+      TraceId traceId,
+      SpanId spanId,
+      String name,
+      @Nullable List<Span> parentLinks) {
+    // Always enable sampling if parent was sampled.
+    if (parentContext != null && parentContext.getTraceOptions().isSampled()) {
+      return true;
+    }
+    // Always sample if we are within probability range. This is true even for child spans (that
+    // may have had a different sampling decision made) to allow for different sampling policies,
+    // and dynamic increases to sampling probabilities for debugging purposes.
+    // Note use of '<' for comparison. This ensures that we never sample for probability == 0.0,
+    // while allowing for a (very) small chance of *not* sampling if the id == Long.MAX_VALUE.
+    // This is considered a reasonable tradeoff for the simplicity/performance requirements (this
+    // code is executed in-line for every Span creation).
+    return Math.abs(traceId.getLowerLong()) < getIdUpperBound();
+  }
+}
diff --git a/api/src/main/java/io/opencensus/trace/samplers/Samplers.java b/api/src/main/java/io/opencensus/trace/samplers/Samplers.java
new file mode 100644
index 00000000..40d72931
--- /dev/null
+++ b/api/src/main/java/io/opencensus/trace/samplers/Samplers.java
@@ -0,0 +1,55 @@
+/*
+ * Copyright 2017, Google Inc.
+ * 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.opencensus.trace.samplers;
+
+import io.opencensus.trace.Span;
+import io.opencensus.trace.base.Sampler;
+
+/** Static class to access a set of pre-defined {@link Sampler Samplers}. */
+public final class Samplers {
+  private static final Sampler ALWAYS_SAMPLE = new AlwaysSampleSampler();
+  private static final Sampler NEVER_SAMPLE = new NeverSampleSampler();
+
+  // No instance of this class.
+  private Samplers() {}
+
+  /**
+   * Returns a {@link Sampler} that always makes a "yes" decision on {@link Span} sampling.
+   *
+   * @return a {@code Sampler} that always makes a "yes" decision on {@code Span} sampling.
+   */
+  public static Sampler alwaysSample() {
+    return ALWAYS_SAMPLE;
+  }
+
+  /**
+   * Returns a {@link Sampler} that always makes a "no" decision on {@link Span} sampling.
+   *
+   * @return a {@code Sampler} that always makes a "no" decision on {@code Span} sampling.
+   */
+  public static Sampler neverSample() {
+    return NEVER_SAMPLE;
+  }
+
+  /**
+   * Returns a {@link Sampler} that makes a "yes" decision with a given probability.
+   *
+   * @param probability The desired probability of sampling. Must be within [0.0, 1.0].
+   * @return a {@code Sampler} that makes a "yes" decision with a given probability.
+   * @throws IllegalArgumentException if {@code probability} is out of range
+   */
+  public static Sampler probabilitySampler(double probability) {
+    return ProbabilitySampler.create(probability);
+  }
+}
diff --git a/api/src/test/java/io/opencensus/trace/SpanBuilderTest.java b/api/src/test/java/io/opencensus/trace/SpanBuilderTest.java
index 469fe9bb..10eccbe6 100644
--- a/api/src/test/java/io/opencensus/trace/SpanBuilderTest.java
+++ b/api/src/test/java/io/opencensus/trace/SpanBuilderTest.java
@@ -23,9 +23,11 @@ import static org.mockito.Mockito.when;
 import io.opencensus.common.NonThrowingCloseable;
 import io.opencensus.trace.base.EndSpanOptions;
 import io.opencensus.trace.base.SpanId;
+import io.opencensus.trace.base.StartSpanOptions;
 import io.opencensus.trace.base.TraceId;
 import io.opencensus.trace.base.TraceOptions;
 import io.opencensus.trace.internal.SpanFactory;
+import io.opencensus.trace.samplers.Samplers;
 import java.util.Arrays;
 import java.util.List;
 import java.util.Random;
diff --git a/api/src/test/java/io/opencensus/trace/TracerTest.java b/api/src/test/java/io/opencensus/trace/TracerTest.java
index 51b86b63..7339eae2 100644
--- a/api/src/test/java/io/opencensus/trace/TracerTest.java
+++ b/api/src/test/java/io/opencensus/trace/TracerTest.java
@@ -24,6 +24,7 @@ import io.grpc.Context;
 import io.opencensus.common.NonThrowingCloseable;
 import io.opencensus.trace.base.EndSpanOptions;
 import io.opencensus.trace.base.SpanId;
+import io.opencensus.trace.base.StartSpanOptions;
 import io.opencensus.trace.base.TraceId;
 import io.opencensus.trace.base.TraceOptions;
 import io.opencensus.trace.internal.SpanFactory;
diff --git a/api/src/test/java/io/opencensus/trace/StartSpanOptionsTest.java b/api/src/test/java/io/opencensus/trace/base/StartSpanOptionsTest.java
index c37324ab..1a983b73 100644
--- a/api/src/test/java/io/opencensus/trace/StartSpanOptionsTest.java
+++ b/api/src/test/java/io/opencensus/trace/base/StartSpanOptionsTest.java
@@ -11,11 +11,14 @@
  * limitations under the License.
  */
 
-package io.opencensus.trace;
+package io.opencensus.trace.base;
 
 import static com.google.common.truth.Truth.assertThat;
 
 import com.google.common.testing.EqualsTester;
+import io.opencensus.trace.BlankSpan;
+import io.opencensus.trace.Span;
+import io.opencensus.trace.samplers.Samplers;
 import java.util.Arrays;
 import java.util.LinkedList;
 import java.util.List;
diff --git a/api/src/test/java/io/opencensus/trace/config/TraceConfigTest.java b/api/src/test/java/io/opencensus/trace/config/TraceConfigTest.java
index 2bf9356d..cbb6092c 100644
--- a/api/src/test/java/io/opencensus/trace/config/TraceConfigTest.java
+++ b/api/src/test/java/io/opencensus/trace/config/TraceConfigTest.java
@@ -15,7 +15,7 @@ package io.opencensus.trace.config;
 
 import static com.google.common.truth.Truth.assertThat;
 
-import io.opencensus.trace.Samplers;
+import io.opencensus.trace.samplers.Samplers;
 import org.junit.Test;
 import org.junit.runner.RunWith;
 import org.junit.runners.JUnit4;
diff --git a/api/src/test/java/io/opencensus/trace/config/TraceParamsTest.java b/api/src/test/java/io/opencensus/trace/config/TraceParamsTest.java
index 76d828a9..165f0211 100644
--- a/api/src/test/java/io/opencensus/trace/config/TraceParamsTest.java
+++ b/api/src/test/java/io/opencensus/trace/config/TraceParamsTest.java
@@ -15,7 +15,7 @@ package io.opencensus.trace.config;
 
 import static com.google.common.truth.Truth.assertThat;
 
-import io.opencensus.trace.Samplers;
+import io.opencensus.trace.samplers.Samplers;
 import org.junit.Test;
 import org.junit.runner.RunWith;
 import org.junit.runners.JUnit4;
diff --git a/api/src/test/java/io/opencensus/trace/SamplersTest.java b/api/src/test/java/io/opencensus/trace/samplers/SamplersTest.java
index 52351f2c..5e996835 100644
--- a/api/src/test/java/io/opencensus/trace/SamplersTest.java
+++ b/api/src/test/java/io/opencensus/trace/samplers/SamplersTest.java
@@ -11,10 +11,13 @@
  * limitations under the License.
  */
 
-package io.opencensus.trace;
+package io.opencensus.trace.samplers;
 
 import static com.google.common.truth.Truth.assertThat;
 
+import io.opencensus.trace.Span;
+import io.opencensus.trace.SpanContext;
+import io.opencensus.trace.base.Sampler;
 import io.opencensus.trace.base.SpanId;
 import io.opencensus.trace.base.TraceId;
 import io.opencensus.trace.base.TraceOptions;
diff --git a/benchmarks/src/jmh/java/io/opencensus/trace/RecordTraceEventsNonSampledSpanBenchmark.java b/benchmarks/src/jmh/java/io/opencensus/trace/RecordTraceEventsNonSampledSpanBenchmark.java
index 13657e1b..3013e764 100644
--- a/benchmarks/src/jmh/java/io/opencensus/trace/RecordTraceEventsNonSampledSpanBenchmark.java
+++ b/benchmarks/src/jmh/java/io/opencensus/trace/RecordTraceEventsNonSampledSpanBenchmark.java
@@ -16,6 +16,7 @@ package io.opencensus.trace;
 import io.opencensus.trace.base.AttributeValue;
 import io.opencensus.trace.base.Link;
 import io.opencensus.trace.base.NetworkEvent;
+import io.opencensus.trace.samplers.Samplers;
 import java.util.HashMap;
 import java.util.concurrent.TimeUnit;
 import org.openjdk.jmh.annotations.Benchmark;
diff --git a/benchmarks/src/jmh/java/io/opencensus/trace/RecordTraceEventsSampledSpanBenchmark.java b/benchmarks/src/jmh/java/io/opencensus/trace/RecordTraceEventsSampledSpanBenchmark.java
index 3c2a9d17..ccfbc775 100644
--- a/benchmarks/src/jmh/java/io/opencensus/trace/RecordTraceEventsSampledSpanBenchmark.java
+++ b/benchmarks/src/jmh/java/io/opencensus/trace/RecordTraceEventsSampledSpanBenchmark.java
@@ -16,6 +16,7 @@ package io.opencensus.trace;
 import io.opencensus.trace.base.AttributeValue;
 import io.opencensus.trace.base.Link;
 import io.opencensus.trace.base.NetworkEvent;
+import io.opencensus.trace.samplers.Samplers;
 import java.util.HashMap;
 import java.util.concurrent.TimeUnit;
 import org.openjdk.jmh.annotations.Benchmark;
diff --git a/benchmarks/src/jmh/java/io/opencensus/trace/StartEndSpanBenchmark.java b/benchmarks/src/jmh/java/io/opencensus/trace/StartEndSpanBenchmark.java
index 9a51ffbe..0a86b6f8 100644
--- a/benchmarks/src/jmh/java/io/opencensus/trace/StartEndSpanBenchmark.java
+++ b/benchmarks/src/jmh/java/io/opencensus/trace/StartEndSpanBenchmark.java
@@ -13,6 +13,7 @@
 
 package io.opencensus.trace;
 
+import io.opencensus.trace.samplers.Samplers;
 import java.util.concurrent.TimeUnit;
 import org.openjdk.jmh.annotations.Benchmark;
 import org.openjdk.jmh.annotations.BenchmarkMode;
diff --git a/core_impl/src/main/java/io/opencensus/trace/SpanFactoryImpl.java b/core_impl/src/main/java/io/opencensus/trace/SpanFactoryImpl.java
index 3f087799..d9aadb5e 100644
--- a/core_impl/src/main/java/io/opencensus/trace/SpanFactoryImpl.java
+++ b/core_impl/src/main/java/io/opencensus/trace/SpanFactoryImpl.java
@@ -20,7 +20,9 @@ import io.opencensus.internal.TimestampConverter;
 import io.opencensus.trace.Span.Options;
 import io.opencensus.trace.base.Link;
 import io.opencensus.trace.base.Link.Type;
+import io.opencensus.trace.base.Sampler;
 import io.opencensus.trace.base.SpanId;
+import io.opencensus.trace.base.StartSpanOptions;
 import io.opencensus.trace.base.TraceId;
 import io.opencensus.trace.base.TraceOptions;
 import io.opencensus.trace.config.TraceConfig;
diff --git a/core_impl/src/test/java/io/opencensus/trace/SpanFactoryImplTest.java b/core_impl/src/test/java/io/opencensus/trace/SpanFactoryImplTest.java
index 4e718cf8..74bc2d86 100644
--- a/core_impl/src/test/java/io/opencensus/trace/SpanFactoryImplTest.java
+++ b/core_impl/src/test/java/io/opencensus/trace/SpanFactoryImplTest.java
@@ -20,11 +20,13 @@ import io.opencensus.internal.TestClock;
 import io.opencensus.trace.Span.Options;
 import io.opencensus.trace.SpanImpl.StartEndHandler;
 import io.opencensus.trace.base.SpanId;
+import io.opencensus.trace.base.StartSpanOptions;
 import io.opencensus.trace.base.TraceId;
 import io.opencensus.trace.base.TraceOptions;
 import io.opencensus.trace.config.TraceConfig;
 import io.opencensus.trace.config.TraceParams;
 import io.opencensus.trace.internal.RandomHandler;
+import io.opencensus.trace.samplers.Samplers;
 import java.util.Random;
 import org.junit.Before;
 import org.junit.Test;
diff --git a/core_impl/src/test/java/io/opencensus/trace/config/TraceConfigImplTest.java b/core_impl/src/test/java/io/opencensus/trace/config/TraceConfigImplTest.java
index 24e78b2b..a76e180f 100644
--- a/core_impl/src/test/java/io/opencensus/trace/config/TraceConfigImplTest.java
+++ b/core_impl/src/test/java/io/opencensus/trace/config/TraceConfigImplTest.java
@@ -15,7 +15,7 @@ package io.opencensus.trace.config;
 
 import static com.google.common.truth.Truth.assertThat;
 
-import io.opencensus.trace.Samplers;
+import io.opencensus.trace.samplers.Samplers;
 import org.junit.Test;
 import org.junit.runner.RunWith;
 import org.junit.runners.JUnit4;