From f089eba4527cdafc2b34067b1ec5a28c0c9b3d9c Mon Sep 17 00:00:00 2001 From: Bogdan Drutu Date: Fri, 21 Aug 2020 07:40:03 -0700 Subject: [PATCH] Add ParentNotRemoteOrElse and fix Probability sampler definition (#610) Signed-off-by: Bogdan Drutu Co-authored-by: Carlos Alberto Cortez --- specification/trace/sdk.md | 45 +++++++++++++++++++++++++------------- 1 file changed, 30 insertions(+), 15 deletions(-) diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index ecae3176144..9531c50bd3f 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -97,7 +97,7 @@ Description MUST NOT change over time and caller can cache the returned value. ### Built-in samplers OpenTelemetry supports a number of built-in samplers to choose from. -The default sampler is `ParentOrElse(AlwaysOn)`. +The default sampler is `ParentBased(root=AlwaysOn)`. #### AlwaysOn @@ -111,27 +111,42 @@ The default sampler is `ParentOrElse(AlwaysOn)`. #### Probability -* The `ProbabilitySampler` MUST ignore the parent `SampledFlag`. - To respect the parent `SampledFlag`, the `ProbabilitySampler` should be used as a delegate of the `ParentOrElse` sampler specified below. +* The `ProbabilitySampler` MUST ignore the parent. To respect the parent +`SampledFlag`, the `ProbabilitySampler` should be used as a delegate of the +`ParentBased` sampler specified below. * Description MUST be `ProbabilitySampler{0.000100}`. TODO: Add details about how the `ProbabilitySampler` is implemented as a function of the `TraceID`. -#### ParentOrElse +#### ParentBased -* 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()}`. +* This is a composite sampler. `ParentBased` helps distinguished between the +following cases: + * No parent (root span). + * Remote parent (`SpanContext.IsRemote() == true`) with `SampledFlag` equals `true` + * Remote parent (`SpanContext.IsRemote() == true`) with `SampledFlag` equals `false` + * Local parent (`SpanContext.IsRemote() == false`) with `SampledFlag` equals `true` + * Local parent (`SpanContext.IsRemote() == false`) with `SampledFlag` equals `false` -|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()`| +Required parameters: + +* `root(Sampler)` - Sampler called for spans with no parent (root spans) + +Optional parameters: + +* `remoteParentSampled(Sampler)` (default: AlwaysOn) +* `remoteParentNotSampled(Sampler)` (default: AlwaysOff) +* `localParentSampled(Sampler)` (default: AlwaysOn) +* `localParentNotSampled(Sampler)` (default: AlwaysOff) + +|Parent| parent.isRemote() | parent.IsSampled()| Invoke sampler| +|--|--|--|--| +|absent| n/a | n/a |`root()`| +|present|true|true|`remoteParentSampled()`| +|present|true|false|`remoteParentNotSampled()`| +|present|false|true|`localParentSampled()`| +|present|false|false|`localParentNotSampled()`| ## Tracer Creation