[dual sampling] support -1 as a priority sampling value (#290)

* [dual sampling] updated tests to make sure -1 and 2 are handled
* [dual sampling] updated doc to mention rules about -1 and 2 sampling priority values
* [dual sampling] adding constants for sampling priority values
* [dual sampling] rephrased documentation

Author: ufoot

docs/GettingStarted.md

@@ -722,9 +722,10 @@ overhead.
 
 Priority sampling consists in deciding if a trace will be kept by using a priority attribute that will be propagated for distributed traces. Its value gives indication to the Agent and to the backend on how important the trace is.
 
-* 0: Don’t keep the trace.
-* 1: The sampler automatically decided to keep the trace.
-* 2: The user asked the keep the trace.
+The sampler can set the priority to the following values:
+
+* `Datadog::Ext::Priority::AUTO_REJECT`: the sampler automatically decided to reject the trace.
+* `Datadog::Ext::Priority::AUTO_KEEP`: the sampler automatically decided to keep the trace.
 
 For now, priority sampling is disabled by default. Enabling it ensures that your sampled distributed traces will be complete. To enable the priority sampling:
 
@@ -734,14 +735,26 @@ Datadog.tracer.configure(priority_sampling: true)
 
 Once enabled, the sampler will automatically assign a priority of 0 or 1 to traces, depending on their service and volume.
 
-You can also set this priority manually to either drop a non-interesting trace or to keep an important one. For that, set the `context#sampling_priority` to 0 or 2. It has to be done before any context propagation (fork, RPC calls) to be effective:
+You can also set this priority manually to either drop a non-interesting trace or to keep an important one. For that, set the `context#sampling_priority` to:
+
+* `Datadog::Ext::Priority::USER_REJECT`: the user asked to reject the trace.
+* `Datadog::Ext::Priority::USER_KEEP`: the user asked to keep the trace.
+
+When not using [distributed tracing](#Distributed_Tracing), you may change the priority at any time,
+as long as the trace is not finished yet.
+But it has to be done before any context propagation (fork, RPC calls) to be effective in a distributed context.
+Changing the priority after context has been propagated causes different parts of a distributed trace
+to use different priorities. Some parts might be kept, some parts might be rejected,
+and this can cause the trace to be partially stored and remain incomplete.
+
+If you change the priority, we recommend you do it as soon as possible, when the root span has just been created.
 
 ```rb
-# Indicate to not keep the trace
-span.context.sampling_priority = 0
+# Indicate to reject the trace
+span.context.sampling_priority = Datadog::Ext::Priority::USER_REJECT
 
 # Indicate to keep the trace
-span.context.sampling_priority = 2
+span.context.sampling_priority = Datadog::Ext::Priority::USER_KEEP
 ```
 
 ### Distributed Tracing

lib/ddtrace/ext/priority.rb

@@ -0,0 +1,16 @@
+module Datadog
+  module Ext
+    # Priority is a hint given to the backend so that it knows which traces to reject or kept.
+    # In a distributed context, it should be set before any context propagation (fork, RPC calls) to be effective.
+    module Priority
+      # Use this to explicitely inform the backend that a trace should be rejected and not stored.
+      USER_REJECT = -1
+      # Used by the builtin sampler to inform the backend that a trace should be rejected and not stored.
+      AUTO_REJECT = 0
+      # Used by the builtin sampler to inform the backend that a trace should be kept and stored.
+      AUTO_KEEP = 1
+      # Use this to explicitely inform the backend that a trace should be kept and stored.
+      USER_KEEP = 2
+    end
+  end
+end

lib/ddtrace/sampler.rb

@@ -1,5 +1,7 @@
 require 'forwardable'
 
+require 'ddtrace/ext/priority'
+
 module Datadog
   # \Sampler performs client-side trace sampling.
   class Sampler
@@ -96,10 +98,10 @@ def initialize(opts = {})
     end
 
     def sample(span)
-      span.context.sampling_priority = 0 if span.context
+      span.context.sampling_priority = Datadog::Ext::Priority::AUTO_REJECT if span.context
       return unless @base_sampler.sample(span)
       return unless @post_sampler.sample(span)
-      span.context.sampling_priority = 1 if span.context
+      span.context.sampling_priority = Datadog::Ext::Priority::AUTO_KEEP if span.context
 
       true
     end

test/context_test.rb

@@ -59,7 +59,11 @@ def test_sampling_priority
 
     assert_nil(ctx.sampling_priority)
 
-    [0, 1, 2, nil, 999].each do |sampling_priority|
+    [Datadog::Ext::Priority::USER_REJECT,
+     Datadog::Ext::Priority::AUTO_REJECT,
+     Datadog::Ext::Priority::AUTO_KEEP,
+     Datadog::Ext::Priority::USER_KEEP,
+     nil, 999].each do |sampling_priority|
       ctx.sampling_priority = sampling_priority
       if sampling_priority
         assert_equal(sampling_priority, ctx.sampling_priority)