Update Sampler interface base on OTEP 0006-sampling

specification/sdk-tracing.md

@@ -29,29 +29,41 @@ as well as a set of [built-in samplers](#built-in-samplers).
 ### Sampler
 
 `Sampler` interface allows to create custom samplers which will return a
-sampling `Decision` based on information that is typically available just before
-the `Span` was created.
+sampling `SamplingResult` based on information that is typically available just
+before the `Span` was created.
 
 #### ShouldSample
 
 Returns the sampling Decision for a `Span` to be created.
 
 **Required arguments:**
 
-- `SpanContext` of a parent `Span`. Typically extracted from the wire. Can be
+* `SpanContext` of a parent `Span`. Typically extracted from the wire. Can be
   `null`.
-- `TraceId` of the `Span` to be created. It can be different from the `TraceId`
+* `TraceId` of the `Span` to be created. It can be different from the `TraceId`
   in the `SpanContext`. Typically in situations when the `Span` to be created
   starts a new Trace.
-- `SpanId` of the `Span` to be created.
-- Name of the `Span` to be created.
-- Collection of links that will be associated with the `Span` to be created.
-  Typically useful for batch operations, see [Links Between
-  Spans](overview.md#links-between-spans).
+* `SpanId` of the `Span` to be created.
+* Name of the `Span` to be created.
+* `SpanKind`
+* Initial set of `Attributes` for the `Span` being constructed
+* Collection of links that will be associated with the `Span` to be created.
+Typically useful for batch operations, see
+[Links Between Spans](overview.md#links-between-spans).
 
 **Return value:**
 
-Sampling `Decision` whether span should be sampled or not.
+It produces an output called `SamplingResult` which contains:
+
+* A `Decision` enum:
+  * `NOT_RECORD` - `IsRecording() == false` and all recorded trace events
+  will be dropped.
+  * `RECORD` - `IsRecording() == true` AND `SampledFlag` is not set.
+  * `RECORD_AND_SAMPLED` - `IsRecording() == true` AND `SampledFlag` is set.
+* A set of span Attributes that will also be added to the `Span`.
+  * The list of attributes returned by `SamplingResult` MUST be immutable.
+  Caller may call this method any number of times and can safely cache the
+  returned value.
 
 #### GetDescription
 
@@ -61,37 +73,31 @@ be displayed on debug pages or in the logs. Example:
 
 Description MUST NOT change over time and caller can cache the returned value.
 
-### Decision
-
-`Decision` is an interface with two getters describing the sampling decision.
-
-#### IsSampled
-
-Return sampling decision whether span should be sampled or not. `True` value of
-`IsSampled` flag means that Span information needs to be recorded.
-
-#### GetAttributes
-
-Return attributes to be attached to the `Span`. These attributes should be added
-to the `Span` only for root span or when sampling decision `IsSampled` changes
-from false to true.
-
-Examples of attribute may be algorithm used to make a decision and sampling
-priority. Another example may be recording the reason trace was marked as
-"important" to sample in. For instance, when traces from specific user session
-should be collected, session identifier can be added to attributes.
-
-The list of attributes returned by `Decision` MUST be immutable. Caller may call
-this method any number of times and can safely cache the returned value.
-
 ### Built-in samplers
 
-API MUST provide a way to create the following built-in samplers:
-
-- Always sample. `Sampler` returns `Decision` with `IsSampled=true` and empty
-  arguments collection. Description MUST be `AlwaysSampleSampler`.
-- Never sample. `Sampler` returns `Decision` with `IsSampled=false` and empty
-  arguments collection. Description MUST be `NeverSampleSampler`.
+These are the default samplers implemented in the OpenTelemetry SDK:
+
+* ALWAYS_ON
+  * This will be used as a default.
+  * Description MUST be `AlwaysOnSampler`.
+* ALWAYS_OFF
+  * Description MUST be `AlwaysOffSampler`.
+* ALWAYS_PARENT
+  * `Returns RECORD_AND_SAMPLED` if `SampledFlag` is set to true on parent
+  SpanContext and `NOT_RECORD` otherwise.
+  * Description MUST be `AlwaysParentSampler`.
+* Probability
+  * The default behavior should be to trust the parent `SampledFlag`. However
+  there should be configuration to change this.
+  * The default behavior is to apply the sampling probability only for Spans
+  that are root spans (no parent) and Spans with remote parent. However there
+  should be configuration to change this to "root spans only", or "all spans".
+  * Description MUST be `ProbabilitySampler{0.000100}`.
+
+#### Probability Sampler algorithm
+
+TODO: Add details about how the probability sampler is implemented as a function
+of the `TraceID`.
 
 ## Tracer Creation