From 33677081bf28c832dd39af10076e6da03b719edc Mon Sep 17 00:00:00 2001 From: Bogdan Drutu Date: Tue, 25 Sep 2018 11:23:12 -0700 Subject: [PATCH 1/3] Add details about Sampler interface and sampling decision. --- trace/Sampling.md | 26 +++++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/trace/Sampling.md b/trace/Sampling.md index 363e13f..a38cbd3 100644 --- a/trace/Sampling.md +++ b/trace/Sampling.md @@ -8,7 +8,31 @@ exporters. The Sampling bit is always set only at the start of a Span, using a `Sampler` -### What kind of samplers does OpenCensus support? +### Sampler interface +A `Sampler` is an interface with only one method `sample` that accepts a set of sampling +parameters and returns a `SamplingDecision` object. + +#### Sampling parameters +Based on the language the sampling parameters can be embedded into an object called +`SamplingParameters` or explicitly passed as arguments. The list of sampling parameters SHOULD +include at least: +* The parent `SpanContext`; +* The current `TraceId`; +* The current `SpanId`; +* The current `Span`'s name; +* The current `Span`'s kind; + +#### SamplingDecision +`SamplingDecision` is the object returned by the `Sampler` and SHOULD include: +* A boolean value that represents the sampling decision; +* A list of `Attribute`'s that are added to the newly created `Span`; + +The list of returned `Attribute`'s MAY include: +* An `Attribute` with a key `sampler.type` to record the type of `Sampler` used. +* An `Attribute` with a key `sampler.param` to record the `Sampler` parameters (e.g. probability). +It can be ignored for `AlwaysSample` or `NeverSample`. + +### What type of samplers does OpenCensus support? * `AlwaysSample` - sampler that makes a "yes" decision every time. * `NeverSample` - sampler that makes a "no" decision every time. * `Probability` - sampler that tries to uniformly sample traces with a given probability. When From 19369a6a5608ac1511f7622d911aeac5b168f9ea Mon Sep 17 00:00:00 2001 From: Bogdan Drutu Date: Tue, 25 Sep 2018 12:14:03 -0700 Subject: [PATCH 2/3] Fix comments, relax implementation details. --- trace/Sampling.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/trace/Sampling.md b/trace/Sampling.md index a38cbd3..d29c13e 100644 --- a/trace/Sampling.md +++ b/trace/Sampling.md @@ -9,23 +9,23 @@ exporters. The Sampling bit is always set only at the start of a Span, using a `Sampler` ### Sampler interface -A `Sampler` is an interface with only one method `sample` that accepts a set of sampling -parameters and returns a `SamplingDecision` object. +A `Sampler` is an interface that returns a `SamplingDecision` based on given sampling parameters. #### Sampling parameters Based on the language the sampling parameters can be embedded into an object called -`SamplingParameters` or explicitly passed as arguments. The list of sampling parameters SHOULD +`SamplingParameters` or explicitly passed as arguments. The set of sampling parameters SHOULD include at least: -* The parent `SpanContext`; -* The current `TraceId`; -* The current `SpanId`; -* The current `Span`'s name; -* The current `Span`'s kind; +* The parent `SpanContext`. +* The current `TraceId`. +* The current `SpanId`. +* The current `Tracestate`. +* The current `Span`'s name. +* The current `Span`'s kind. #### SamplingDecision `SamplingDecision` is the object returned by the `Sampler` and SHOULD include: -* A boolean value that represents the sampling decision; -* A list of `Attribute`'s that are added to the newly created `Span`; +* A boolean value that represents the sampling decision. +* A list of `Attribute`'s that are added to the newly created `Span`. The list of returned `Attribute`'s MAY include: * An `Attribute` with a key `sampler.type` to record the type of `Sampler` used. From f3d1a72e6d24ad3c0a0458276b89890dec14139a Mon Sep 17 00:00:00 2001 From: Bogdan Drutu Date: Tue, 25 Sep 2018 15:49:44 -0700 Subject: [PATCH 3/3] Fix a grammer issue. --- trace/Sampling.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/trace/Sampling.md b/trace/Sampling.md index d29c13e..f65d779 100644 --- a/trace/Sampling.md +++ b/trace/Sampling.md @@ -25,7 +25,7 @@ include at least: #### SamplingDecision `SamplingDecision` is the object returned by the `Sampler` and SHOULD include: * A boolean value that represents the sampling decision. -* A list of `Attribute`'s that are added to the newly created `Span`. +* A list of `Attribute`'s that will be added to the newly created `Span`. The list of returned `Attribute`'s MAY include: * An `Attribute` with a key `sampler.type` to record the type of `Sampler` used.