From 134ccfc815764447c1c4ded820b0bbc514fe2b0b Mon Sep 17 00:00:00 2001 From: Brett McBride Date: Wed, 17 Jul 2024 03:30:03 +0000 Subject: [PATCH 1/4] adding rule-based sampler this is based on PHP's implementation of a rules-based sampler, which itself is based on extending Java's implementation. --- specification/trace/sdk.md | 58 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 4208c4d89d5..39017e1c50f 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -447,6 +447,64 @@ Optional parameters: |present|false|true|`localParentSampled()`| |present|false|false|`localParentNotSampled()`| +#### RuleBased + +A `RuleBased` sampler tests a span against a list of rules, and delegates the +sampling decision to another sampler when a rule matches. If no rules match, a +fallback sampler is used to make the sampling decision. + +The obvious use-case for a `RuleBased` sampler is to avoid tracing frequent and +uninteresting transactions such as health checks. + +* A `RuleBased` sampler MUST be configured with a set of rules and a fallback + `Sampler` to use if the `Span` does not match any of the configured rules. The + rules MUST be processed in the order they were provided. +* A `Rule` requires a list of tests, and a delegate `Sampler` to be invoked if + all of the tests match the `Span` being sampled. If multiple tests are + configured, then the rule MUST pass if *all* tests pass. +* If no rules match, the sampling decision MUST be made by the configured + fallback sampler. +* A test can be based on the parameters available to [`ShouldSample`](#shouldsample): + * `parent` + * `sampled` - boolean representing whether the parent is sampled + * `remote` - boolean representing whether the parent is remote + * `span_name` + * `pattern` - regular expression to match on + * `span_kind` + * `kind` - one of [SpanKind](./api.md#spankind), for example `SERVER` + * `attributes` + * `key` and `pattern` - attribute key and regular expression pattern to match on + * `link` + * `sampled` - boolean representing whether a link is sampled + * `remote` - boolean representing whether a link is remote +* Description MUST start with `RuleBased`, and MAY contain further details of the +configuration, such as `RuleBasedSampler{rules=[RuleSet{rules=[Attribute{key=http.request.url,pattern=^/health$}],delegate=always_off}],fallback=parent_based_always_on}` + +An example YAML-based configuration for a `RuleBased` sampler with multiple rules: + +```yaml +sampler: + rule_based: + rule_sets: + - rules: + - span_kind: { kind: SERVER } + - attribute: { key: url.path, pattern: "^/health$" } + delegate: + always_off: {} + - rules: + - link: { sampled: true } + delegate: + always_on: {} + fallback: + parent_based_always_on: {} +``` + +The above sampler will: + +* Use an `AlwaysOff` sampler for any `SERVER` span with a url path matching the regular expression `^/health$` +* Use an `AlwaysOn` sampler for any span with a link that is sampled +* Use a `ParentBased,AlwaysOn` sampler for all other spans + #### JaegerRemoteSampler [Jaeger remote sampler][jaeger-remote-sampling] allows remotely controlling the sampling configuration for the SDKs. The sampling configuration is periodically loaded from the backend (see [Remote Sampling API][jaeger-remote-sampling-api]), where it can be managed by operators via configuration files or even automatically calculated (see [Adaptive Sampling][jaeger-adaptive-sampling]). The sampling configuration retrieved by the remote sampler can instruct it to use either a single sampling method for the whole service (e.g., `TraceIdRatioBased`), or different methods for different endpoints (span names), for example, sample `/product` endpoint at 10%, `/admin` endpoint at 100%, and never sample `/metrics` endpoint. From e025a5e9edf8a3cc66d12d9c0c5aaf926d8f0cd0 Mon Sep 17 00:00:00 2001 From: Brett McBride Date: Wed, 17 Jul 2024 03:51:52 +0000 Subject: [PATCH 2/4] spec compliance matrix + changelog --- CHANGELOG.md | 2 ++ spec-compliance-matrix.md | 1 + 2 files changed, 3 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6deddc0e763..6fdbc523cc8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,6 +11,8 @@ release. ### Traces + - Add `RulesBased` sampler. [#4152](https://github.com/open-telemetry/opentelemetry-specification/pull/4152) + ### Metrics ### Logs diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index 8d505c4a7e3..2d00cbdb382 100644 --- a/spec-compliance-matrix.md +++ b/spec-compliance-matrix.md @@ -79,6 +79,7 @@ formats is required. Implementing more than one format is optional. | [Sampling](specification/trace/sdk.md#sampling) | Optional | Go | Java | JS | Python | Ruby | Erlang | PHP | Rust | C++ | .NET | Swift | | Allow samplers to modify tracestate | | + | + | | + | + | + | + | + | + | + | + | | ShouldSample gets full parent Context | | + | + | + | + | + | + | + | + | + | - | + | +| Sampler: RulesBasedSampler | Optional | | | | | | | | | | | | | Sampler: JaegerRemoteSampler | | + | + | | | | | | + | | | | | [New Span ID created also for non-recording Spans](specification/trace/sdk.md#sdk-span-creation) | | + | + | | + | + | + | + | + | + | - | + | | [IdGenerators](specification/trace/sdk.md#id-generators) | | + | + | | + | + | + | + | + | + | | + | From 81b75dc9c2ec6c38a0a12bc08c73b0f23bd056fd Mon Sep 17 00:00:00 2001 From: Brett McBride Date: Wed, 17 Jul 2024 04:17:49 +0000 Subject: [PATCH 3/4] markdown + toc --- CHANGELOG.md | 2 +- specification/trace/sdk.md | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6fdbc523cc8..592cbc2bdda 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,7 +11,7 @@ release. ### Traces - - Add `RulesBased` sampler. [#4152](https://github.com/open-telemetry/opentelemetry-specification/pull/4152) +- Add `RulesBased` sampler. [#4152](https://github.com/open-telemetry/opentelemetry-specification/pull/4152) ### Metrics diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 39017e1c50f..7b96b80a332 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -32,6 +32,7 @@ linkTitle: SDK + [TraceIdRatioBased](#traceidratiobased) - [Requirements for `TraceIdRatioBased` sampler algorithm](#requirements-for-traceidratiobased-sampler-algorithm) + [ParentBased](#parentbased) + + [RuleBased](#rulebased) + [JaegerRemoteSampler](#jaegerremotesampler) - [Span Limits](#span-limits) - [Id Generators](#id-generators) From ef2c9cb64e32cc59861ea511dacf33be8f28b2bb Mon Sep 17 00:00:00 2001 From: Brett McBride Date: Wed, 17 Jul 2024 04:22:18 +0000 Subject: [PATCH 4/4] link to sampler from compliance matrix --- spec-compliance-matrix.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index 2d00cbdb382..af04d6d2b45 100644 --- a/spec-compliance-matrix.md +++ b/spec-compliance-matrix.md @@ -79,7 +79,7 @@ formats is required. Implementing more than one format is optional. | [Sampling](specification/trace/sdk.md#sampling) | Optional | Go | Java | JS | Python | Ruby | Erlang | PHP | Rust | C++ | .NET | Swift | | Allow samplers to modify tracestate | | + | + | | + | + | + | + | + | + | + | + | | ShouldSample gets full parent Context | | + | + | + | + | + | + | + | + | + | - | + | -| Sampler: RulesBasedSampler | Optional | | | | | | | | | | | | +| Sampler: [RulesBasedSampler](specification/trace/sdk.md#rulebased) | Optional | | | | | | | | | | | | | Sampler: JaegerRemoteSampler | | + | + | | | | | | + | | | | | [New Span ID created also for non-recording Spans](specification/trace/sdk.md#sdk-span-creation) | | + | + | | + | + | + | + | + | + | - | + | | [IdGenerators](specification/trace/sdk.md#id-generators) | | + | + | | + | + | + | + | + | + | | + |