Replace ALWAYS_PARENT with a composite ParentOrElse sampler (open-telemetry#609)

* Split ALWAYS_PARENT based on default behavior if no parent

Signed-off-by: Bogdan Drutu <bogdandrutu@gmail.com>

* Rename RootOnly to ParentOrElse

Signed-off-by: Bogdan Drutu <bogdandrutu@gmail.com>

* Address feedback

Signed-off-by: Bogdan Drutu <bogdandrutu@gmail.com>

* More feedback

Signed-off-by: Bogdan Drutu <bogdandrutu@gmail.com>

Author: bogdandrutu

specification/trace/sdk.md

@@ -101,29 +101,44 @@ Description MUST NOT change over time and caller can cache the returned value.
 
 ### Built-in samplers
 
-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
+#### AlwaysOn
+
+* This is the default sampler.
+* Returns `RECORD_AND_SAMPLED` always.
+* Description MUST be `AlwaysOnSampler`.
+
+#### AlwaysOff
+
+* Returns `NOT_RECORD` always.
+* Description MUST be `AlwaysOffSampler`.
+
+#### 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
+* 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
+* Description MUST be `ProbabilitySampler{0.000100}`.
 
 TODO: Add details about how the probability sampler is implemented as a function
 of the `TraceID`.
+TODO: Split out the parent handling.
+
+#### ParentOrElse
+
+* This is a composite sampler. `ParentOrElse(delegateSampler)` either respects the parent span's sampling decision or delegates to  `delegateSampler` for root spans.
+* If parent exists:
+  * If parent's `SampledFlag` is set to `true` returns `RECORD_AND_SAMPLED`
+  * If parent's `SampledFlag` is set to `false` returns `NOT_RECORD`
+* If no parent (root span) exists returns the result of the `delegateSampler`.
+* Description MUST be `ParentOrElse{delegateSampler.getDescription()}`.
+
+|Parent|`ParentOrElse(delegateSampler)`
+|--|--|
+|Exists and `SampledFlag` is `true`|`RECORD_AND_SAMPLED`|
+|Exists and `SampledFlag` is `false`|`NOT_RECORD`|
+|No parent(root spans)|Result of `delegateSampler()`|
 
 ## Tracer Creation