RandomSampler provides a static factory, preferred over the constructor (#561)

RandomSampler provides a static factory, preferred over the constructor to  advantage of deterministic values (zero and one).

Author: carterkozak

changelog/@unreleased/pr-561.v2.yml

@@ -0,0 +1,6 @@
+type: improvement
+improvement:
+  description: RandomSampler provides a static factory, preferred over the constructor
+    to  advantage of deterministic values (zero and one).
+  links:
+  - https://github.com/palantir/tracing-java/pull/561

tracing-benchmarks/src/jmh/java/com/palantir/tracing/TracingBenchmark.java

@@ -54,7 +54,7 @@ public class TracingBenchmark {
     public enum BenchmarkObservability {
         SAMPLE(AlwaysSampler.INSTANCE),
         DO_NOT_SAMPLE(() -> false),
-        UNDECIDED(new RandomSampler(0.01f));
+        UNDECIDED(RandomSampler.create(0.01f));
 
         private final TraceSampler traceSampler;
 

tracing/src/main/java/com/palantir/tracing/NeverSampler.java

@@ -0,0 +1,26 @@
+/*
+ * (c) Copyright 2018 Palantir Technologies Inc. All rights reserved.
+ *
+ * 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 com.palantir.tracing;
+
+enum NeverSampler implements TraceSampler {
+    INSTANCE;
+
+    @Override
+    public boolean sample() {
+        return false;
+    }
+}

tracing/src/main/java/com/palantir/tracing/RandomSampler.java

@@ -29,11 +29,29 @@ public final class RandomSampler implements TraceSampler {
 
     private final float rate;
 
+    /**
+     * Prefer the factory method {@link RandomSampler#create(float)}.
+     *
+     * @deprecated prefer the factory method
+     */
+    @Deprecated
     public RandomSampler(float rate) {
         checkArgument(rate >= 0 && rate <= 1, "Rate should be between 0 and 1", SafeArg.of("rate", rate));
         this.rate = rate;
     }
 
+    public static TraceSampler create(float rate) {
+        checkArgument(rate >= 0 && rate <= 1, "Rate should be between 0 and 1", SafeArg.of("rate", rate));
+        if (rate == 0) {
+            return NeverSampler.INSTANCE;
+        }
+
+        if (rate == 1) {
+            return AlwaysSampler.INSTANCE;
+        }
+        return new RandomSampler(rate);
+    }
+
     @Override
     public boolean sample() {
         return ThreadLocalRandom.current().nextFloat() < rate;

tracing/src/main/java/com/palantir/tracing/Tracer.java

@@ -66,7 +66,7 @@ private Tracer() {}
     private static volatile Consumer<Span> compositeObserver = span -> {};
 
     // Thread-safe since stateless
-    private static volatile TraceSampler sampler = new RandomSampler(0.01f);
+    private static volatile TraceSampler sampler = RandomSampler.create(0.01f);
 
     /** Creates a new trace, but does not set it as the current trace. */
     private static Trace createTrace(Observability observability, String traceId) {