From d3f0615c6fb53fddafcc16a5465e7960af73bade Mon Sep 17 00:00:00 2001 From: Michael Hoffmann Date: Tue, 5 Nov 2024 08:37:13 +0100 Subject: [PATCH 1/5] docs(sdks): Span Sampling --- develop-docs/sdk/telemetry/spans/index.mdx | 6 + .../sdk/telemetry/spans/span-sampling.mdx | 105 ++++++++++++++++++ 2 files changed, 111 insertions(+) create mode 100644 develop-docs/sdk/telemetry/spans/index.mdx create mode 100644 develop-docs/sdk/telemetry/spans/span-sampling.mdx diff --git a/develop-docs/sdk/telemetry/spans/index.mdx b/develop-docs/sdk/telemetry/spans/index.mdx new file mode 100644 index 00000000000000..6853b90e443fdb --- /dev/null +++ b/develop-docs/sdk/telemetry/spans/index.mdx @@ -0,0 +1,6 @@ +--- +title: Spans +sidebar_order: 8 +--- + + diff --git a/develop-docs/sdk/telemetry/spans/span-sampling.mdx b/develop-docs/sdk/telemetry/spans/span-sampling.mdx new file mode 100644 index 00000000000000..d152eae72e822b --- /dev/null +++ b/develop-docs/sdk/telemetry/spans/span-sampling.mdx @@ -0,0 +1,105 @@ +--- +title: Span Sampling & Filtering +--- + + This document uses key words such as "MUST", "SHOULD", and "MAY" as defined in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) to indicate requirement levels. + + +Any APIs exposed to the user to sample or filter spans must adhere to the following design principles: + +- The APIs are optimized for trace completeness +- The APIs are optimized for conclusive sampling decisions + +## Sample root spans with `tracesSampleRate` & `tracesSampler` + +The SDK is automatically initialized with a `tracesSampleRate` of `0`. +When starting a root span, the configured rate is compared against a random number between 0 and 1 to decide if this root span will be sampled or not. + +If the SDK is configured with a `tracesSampler`, the `tracesSampleRate` no longer applies. +The `tracesSampler` callback must receive sufficient arguments from users to define their own sampling rules. +This can include but is not limited to certain attributes from the root span, such as HTTP headers. +The return value of the `tracesSampler` is a float between `0.0` and `1.0`. + +```js +Sentry.init({ + tracesSampler: ({ name, attributes, parentSampleRate }) => { + // Inherit the trace parent's sample rate if there is one. Sampling is deterministic + // for one trace, e.g. if the parent was sampled, all children will be sampled at the same rate. + if (typeof parentSampleRate === "number") { + return parentSampleRate; + } + + // Else, use a default sample rate (replacing tracesSampleRate). + return 0.5; + } +}) +``` + +The `parentSampleRate` is a propagated value inside the baggage, using key `sentry-sample_rand`. +The value stems from a truly random number between 0 and 1, generated when a new trace is started. If the SDK does not receive such a number in an incoming trace, a new, truly random number between 0 and 1 is generated. + +In the following cases, the SDK must compare sample rates against this `parentSampleRate` instead of `math.random()`: + + - When a `tracesSampler` is configured, i.e. `trace["sentry-sample_rand"] < tracesSampler()` + + - When the SDK is the head of trace, this applies to sample decisions based on `tracesSampleRate`, e.g. `trace['sentry-sample_rand'] < config.tracesSampleRate` + +If the `sentry-sample_rate` (`parentSampleRate`) is not available for any reason for an inbound trace, but the trace has the sampled flag set to true, the SDK injects `parentSampleRate: 1.0` into the `tracesSampler`. + +If no `tracesSampler` is configured, a propagated sampling decision via the traceparent takes precedence over the `tracesSampleRate`. This behavior can be disabled by defining a `tracesSampler`. + +## Parent Sampling Origins + +If the SDK can parse an org ID from the configured DSN, this value must be propagated as a baggage entry with the key `sentry-org`. Given a DSN of `https://1234@o1.ingest.us.sentry.io/1`, the org ID is 1, based on `o1`. + +On incoming traces, the SDK must compare the `sentry-org` baggage value against its own parsed value from the DSN. Only if both match, the parent sampling decisions applies. + +This behavior can be disabled by setting `strictTracePropagation: false` in the SDK init call. + +The SDK must be configurable with an optional `org: ` setting that takes precedence over the parsed value from the DSN. + +## Filter spans with `ignoreSpans` & integration config + +The SDK must implement a mechanism for users to filter out spans. The result must be binary (true/false). +The `ignoreSpans` option accepts a glob pattern or string. +The `integrations` option can perform in similar fashion or make explicit opt-out possible via a bool flag. + +If both options are not feasible to be implemented in certain SDKs, other approaches must be explored that have the same outcome. + +```js +Sentry.init({ + ignoreSpans: [ + 'GET /about', + 'events.signal *', + ], + integrations: [ + fsIntegration: { + ignoreSpans: [ + 'fs.read', + ], + readSpans: true, + writeSpans: false, + } + ] +}) +``` + +## Sanitize span attributes with `beforeSendSpans` + +This callback must not allow the removal of any spans from the span tree. +It receives a deep copy of all spans in the span tree and their attributes. + +``` +[ + { + 'name': 'GET /', + 'attributes': [ + 'http.request.method': 'GET', + 'http.response.status_code': 200, + ] + }, +] +``` + +Users can mutate any exposed properties to perform sanitation on sensitive data or Pii. +The return value `beforeSendSpans` should be merged with the original span tree prior to emission. From 220481463ab17982f7133ffe7fd1ad42ac9903b0 Mon Sep 17 00:00:00 2001 From: Michael Hoffmann Date: Mon, 25 Nov 2024 16:36:34 +0100 Subject: [PATCH 2/5] Remove out-of-scope items --- .../sdk/telemetry/spans/span-sampling.mdx | 36 ------------------- 1 file changed, 36 deletions(-) diff --git a/develop-docs/sdk/telemetry/spans/span-sampling.mdx b/develop-docs/sdk/telemetry/spans/span-sampling.mdx index d152eae72e822b..6c709a176eb8a3 100644 --- a/develop-docs/sdk/telemetry/spans/span-sampling.mdx +++ b/develop-docs/sdk/telemetry/spans/span-sampling.mdx @@ -20,43 +20,7 @@ The `tracesSampler` callback must receive sufficient arguments from users to def This can include but is not limited to certain attributes from the root span, such as HTTP headers. The return value of the `tracesSampler` is a float between `0.0` and `1.0`. -```js -Sentry.init({ - tracesSampler: ({ name, attributes, parentSampleRate }) => { - // Inherit the trace parent's sample rate if there is one. Sampling is deterministic - // for one trace, e.g. if the parent was sampled, all children will be sampled at the same rate. - if (typeof parentSampleRate === "number") { - return parentSampleRate; - } - - // Else, use a default sample rate (replacing tracesSampleRate). - return 0.5; - } -}) -``` - -The `parentSampleRate` is a propagated value inside the baggage, using key `sentry-sample_rand`. -The value stems from a truly random number between 0 and 1, generated when a new trace is started. If the SDK does not receive such a number in an incoming trace, a new, truly random number between 0 and 1 is generated. - -In the following cases, the SDK must compare sample rates against this `parentSampleRate` instead of `math.random()`: - - - When a `tracesSampler` is configured, i.e. `trace["sentry-sample_rand"] < tracesSampler()` - - - When the SDK is the head of trace, this applies to sample decisions based on `tracesSampleRate`, e.g. `trace['sentry-sample_rand'] < config.tracesSampleRate` - -If the `sentry-sample_rate` (`parentSampleRate`) is not available for any reason for an inbound trace, but the trace has the sampled flag set to true, the SDK injects `parentSampleRate: 1.0` into the `tracesSampler`. - If no `tracesSampler` is configured, a propagated sampling decision via the traceparent takes precedence over the `tracesSampleRate`. This behavior can be disabled by defining a `tracesSampler`. - -## Parent Sampling Origins - -If the SDK can parse an org ID from the configured DSN, this value must be propagated as a baggage entry with the key `sentry-org`. Given a DSN of `https://1234@o1.ingest.us.sentry.io/1`, the org ID is 1, based on `o1`. - -On incoming traces, the SDK must compare the `sentry-org` baggage value against its own parsed value from the DSN. Only if both match, the parent sampling decisions applies. - -This behavior can be disabled by setting `strictTracePropagation: false` in the SDK init call. - -The SDK must be configurable with an optional `org: ` setting that takes precedence over the parsed value from the DSN. ## Filter spans with `ignoreSpans` & integration config From a3e26134e8a141a9ba63a7b57e6dd4e59ce4acf1 Mon Sep 17 00:00:00 2001 From: Stephanie Anderson Date: Tue, 26 Nov 2024 10:15:43 +0100 Subject: [PATCH 3/5] chore(wording): Apply RFC keywords MUST, SHOULD and MAY --- .../sdk/telemetry/spans/span-sampling.mdx | 25 ++++++++++--------- 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/develop-docs/sdk/telemetry/spans/span-sampling.mdx b/develop-docs/sdk/telemetry/spans/span-sampling.mdx index 6c709a176eb8a3..2bf2db5c2163be 100644 --- a/develop-docs/sdk/telemetry/spans/span-sampling.mdx +++ b/develop-docs/sdk/telemetry/spans/span-sampling.mdx @@ -1,34 +1,35 @@ --- title: Span Sampling & Filtering --- + This document uses key words such as "MUST", "SHOULD", and "MAY" as defined in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) to indicate requirement levels. -Any APIs exposed to the user to sample or filter spans must adhere to the following design principles: +Any APIs exposed to the user to sample or filter spans MUST adhere to the following design principles: - The APIs are optimized for trace completeness - The APIs are optimized for conclusive sampling decisions ## Sample root spans with `tracesSampleRate` & `tracesSampler` -The SDK is automatically initialized with a `tracesSampleRate` of `0`. -When starting a root span, the configured rate is compared against a random number between 0 and 1 to decide if this root span will be sampled or not. +The SDK is automatically initialized with a `tracesSampleRate` of `0.0`. +When starting a root span, the configured rate is compared against a random number between `0.0` and `1.0` to decide if this root span will be sampled or not. If the SDK is configured with a `tracesSampler`, the `tracesSampleRate` no longer applies. -The `tracesSampler` callback must receive sufficient arguments from users to define their own sampling rules. -This can include but is not limited to certain attributes from the root span, such as HTTP headers. +The `tracesSampler` callback MUST receive sufficient arguments from users to define their own sampling rules. +This MAY include but is not limited to certain attributes from the root span, such as HTTP headers. The return value of the `tracesSampler` is a float between `0.0` and `1.0`. -If no `tracesSampler` is configured, a propagated sampling decision via the traceparent takes precedence over the `tracesSampleRate`. This behavior can be disabled by defining a `tracesSampler`. +If no `tracesSampler` is configured, a propagated sampling decision via the traceparent takes precedence over the `tracesSampleRate`. This behavior MAY be disabled by defining a `tracesSampler`. ## Filter spans with `ignoreSpans` & integration config -The SDK must implement a mechanism for users to filter out spans. The result must be binary (true/false). +The SDK MUST implement a mechanism for users to filter out spans. The result MUST be binary (true/false). The `ignoreSpans` option accepts a glob pattern or string. -The `integrations` option can perform in similar fashion or make explicit opt-out possible via a bool flag. +The `integrations` option MAY perform in similar fashion or make explicit opt-out possible via a bool flag. -If both options are not feasible to be implemented in certain SDKs, other approaches must be explored that have the same outcome. +If both options are not feasible to be implemented in certain SDKs, other approaches MUST be explored that have the same outcome. ```js Sentry.init({ @@ -50,7 +51,7 @@ Sentry.init({ ## Sanitize span attributes with `beforeSendSpans` -This callback must not allow the removal of any spans from the span tree. +This callback MUST NOT allow the removal of any spans from the span tree. It receives a deep copy of all spans in the span tree and their attributes. ``` @@ -65,5 +66,5 @@ It receives a deep copy of all spans in the span tree and their attributes. ] ``` -Users can mutate any exposed properties to perform sanitation on sensitive data or Pii. -The return value `beforeSendSpans` should be merged with the original span tree prior to emission. +Users MAY mutate any exposed properties to perform sanitation on sensitive data or PII. +The return value of `beforeSendSpans` MUST be merged with the original span tree prior to emission. From ce0f629ae438dcbd37b6bdc833b449b42c2b498a Mon Sep 17 00:00:00 2001 From: Stephanie Anderson Date: Tue, 26 Nov 2024 10:54:30 +0100 Subject: [PATCH 4/5] chore(docs): split contents into separate files --- .../sdk/telemetry/spans/filtering.mdx | 49 +++++++++++++ develop-docs/sdk/telemetry/spans/sampling.mdx | 28 ++++++++ .../sdk/telemetry/spans/scrubbing-data.mdx | 27 +++++++ .../sdk/telemetry/spans/span-sampling.mdx | 70 ------------------- 4 files changed, 104 insertions(+), 70 deletions(-) create mode 100644 develop-docs/sdk/telemetry/spans/filtering.mdx create mode 100644 develop-docs/sdk/telemetry/spans/sampling.mdx create mode 100644 develop-docs/sdk/telemetry/spans/scrubbing-data.mdx delete mode 100644 develop-docs/sdk/telemetry/spans/span-sampling.mdx diff --git a/develop-docs/sdk/telemetry/spans/filtering.mdx b/develop-docs/sdk/telemetry/spans/filtering.mdx new file mode 100644 index 00000000000000..a8a0d96e86a07a --- /dev/null +++ b/develop-docs/sdk/telemetry/spans/filtering.mdx @@ -0,0 +1,49 @@ +--- +title: Filtering +--- + + + This document uses key words such as "MUST", "SHOULD", and "MAY" as defined in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) to indicate requirement levels. + + +The SDK MUST implement a mechanism for users to filter out spans. +The result MUST be binary (`true` or `false`). +Any APIs exposed to the user to filter spans MUST adhere to the following design principles: + +- The APIs are optimized for trace completeness +- The APIs are optimized for conclusive sampling decisions + +## Filter with `ignoreSpans` + +The `ignoreSpans` option accepts a glob pattern or string. + +```js +Sentry.init({ + ignoreSpans: [ + 'GET /about', + 'events.signal *', + ] +}) +``` + +## Filter with `integrations` + +The `integrations` option MAY perform in similar fashion as the `ignoreSpans` option, or make explicit opt-out possible via a boolean flag. + +```js +Sentry.init({ + integrations: [ + fsIntegration: { + ignoreSpans: [ + 'fs.read', + ], + readSpans: true, + writeSpans: false, + } + ] +}) +``` + +## Other approaches + +If both options mentioned above are not feasible to be implemented in certain SDKs, other approaches MUST be explored that have the same outcome. diff --git a/develop-docs/sdk/telemetry/spans/sampling.mdx b/develop-docs/sdk/telemetry/spans/sampling.mdx new file mode 100644 index 00000000000000..ce90306f553f63 --- /dev/null +++ b/develop-docs/sdk/telemetry/spans/sampling.mdx @@ -0,0 +1,28 @@ +--- +title: Sampling +--- + + + This document uses key words such as "MUST", "SHOULD", and "MAY" as defined in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) to indicate requirement levels. + + +Any APIs exposed to the user to sample spans MUST adhere to the following design principles: + +- Sampling MUST only happen to a root span +- The APIs are optimized for trace completeness +- The APIs are optimized for conclusive sampling decisions + +## Sample with `tracesSampleRate` + +The SDK is automatically initialized with a `tracesSampleRate` of `0.0`. +When starting a root span, the configured rate is compared against a random number between `0.0` and `1.0` to decide if this root span will be sampled or not. + +## Sample with `tracesSampler` + +If the SDK is configured with a `tracesSampler`, the `tracesSampleRate` no longer applies. + +The `tracesSampler` callback MUST receive sufficient arguments from users to define their own sampling rules. +This MAY include but is not limited to certain attributes from the root span, such as HTTP headers. +The return value of the `tracesSampler` is a float between `0.0` and `1.0`. + +If no `tracesSampler` is configured, a propagated sampling decision via the traceparent takes precedence over the `tracesSampleRate`. This behavior MAY be disabled by defining a `tracesSampler`. diff --git a/develop-docs/sdk/telemetry/spans/scrubbing-data.mdx b/develop-docs/sdk/telemetry/spans/scrubbing-data.mdx new file mode 100644 index 00000000000000..489fd60aad1afa --- /dev/null +++ b/develop-docs/sdk/telemetry/spans/scrubbing-data.mdx @@ -0,0 +1,27 @@ +--- +title: Scrubbing data +--- + + + This document uses key words such as "MUST", "SHOULD", and "MAY" as defined in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) to indicate requirement levels. + + +## Scrubbing data with `beforeSendSpans` + +This callback MUST NOT allow the removal of any spans from the span tree. +It receives a deep copy of all spans in the span tree and their attributes. + +``` +[ + { + 'name': 'GET /', + 'attributes': [ + 'http.request.method': 'GET', + 'http.response.status_code': 200, + ] + }, +] +``` + +Users MAY mutate any exposed properties to perform sanitation on sensitive data or PII. +The return value of `beforeSendSpans` MUST be merged with the original span tree prior to emission. diff --git a/develop-docs/sdk/telemetry/spans/span-sampling.mdx b/develop-docs/sdk/telemetry/spans/span-sampling.mdx deleted file mode 100644 index 2bf2db5c2163be..00000000000000 --- a/develop-docs/sdk/telemetry/spans/span-sampling.mdx +++ /dev/null @@ -1,70 +0,0 @@ ---- -title: Span Sampling & Filtering ---- - - - This document uses key words such as "MUST", "SHOULD", and "MAY" as defined in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) to indicate requirement levels. - - -Any APIs exposed to the user to sample or filter spans MUST adhere to the following design principles: - -- The APIs are optimized for trace completeness -- The APIs are optimized for conclusive sampling decisions - -## Sample root spans with `tracesSampleRate` & `tracesSampler` - -The SDK is automatically initialized with a `tracesSampleRate` of `0.0`. -When starting a root span, the configured rate is compared against a random number between `0.0` and `1.0` to decide if this root span will be sampled or not. - -If the SDK is configured with a `tracesSampler`, the `tracesSampleRate` no longer applies. -The `tracesSampler` callback MUST receive sufficient arguments from users to define their own sampling rules. -This MAY include but is not limited to certain attributes from the root span, such as HTTP headers. -The return value of the `tracesSampler` is a float between `0.0` and `1.0`. - -If no `tracesSampler` is configured, a propagated sampling decision via the traceparent takes precedence over the `tracesSampleRate`. This behavior MAY be disabled by defining a `tracesSampler`. - -## Filter spans with `ignoreSpans` & integration config - -The SDK MUST implement a mechanism for users to filter out spans. The result MUST be binary (true/false). -The `ignoreSpans` option accepts a glob pattern or string. -The `integrations` option MAY perform in similar fashion or make explicit opt-out possible via a bool flag. - -If both options are not feasible to be implemented in certain SDKs, other approaches MUST be explored that have the same outcome. - -```js -Sentry.init({ - ignoreSpans: [ - 'GET /about', - 'events.signal *', - ], - integrations: [ - fsIntegration: { - ignoreSpans: [ - 'fs.read', - ], - readSpans: true, - writeSpans: false, - } - ] -}) -``` - -## Sanitize span attributes with `beforeSendSpans` - -This callback MUST NOT allow the removal of any spans from the span tree. -It receives a deep copy of all spans in the span tree and their attributes. - -``` -[ - { - 'name': 'GET /', - 'attributes': [ - 'http.request.method': 'GET', - 'http.response.status_code': 200, - ] - }, -] -``` - -Users MAY mutate any exposed properties to perform sanitation on sensitive data or PII. -The return value of `beforeSendSpans` MUST be merged with the original span tree prior to emission. From ff4860a3168f67f992637dd7598ef28171a555b2 Mon Sep 17 00:00:00 2001 From: Stephanie Anderson Date: Tue, 26 Nov 2024 10:57:11 +0100 Subject: [PATCH 5/5] chore(docs): indicate work in progress --- develop-docs/sdk/telemetry/spans/filtering.mdx | 4 ++++ develop-docs/sdk/telemetry/spans/sampling.mdx | 4 ++++ develop-docs/sdk/telemetry/spans/scrubbing-data.mdx | 4 ++++ 3 files changed, 12 insertions(+) diff --git a/develop-docs/sdk/telemetry/spans/filtering.mdx b/develop-docs/sdk/telemetry/spans/filtering.mdx index a8a0d96e86a07a..5ef9a8d6223efe 100644 --- a/develop-docs/sdk/telemetry/spans/filtering.mdx +++ b/develop-docs/sdk/telemetry/spans/filtering.mdx @@ -2,6 +2,10 @@ title: Filtering --- + + 🚧 This document is work in progress. + + This document uses key words such as "MUST", "SHOULD", and "MAY" as defined in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) to indicate requirement levels. diff --git a/develop-docs/sdk/telemetry/spans/sampling.mdx b/develop-docs/sdk/telemetry/spans/sampling.mdx index ce90306f553f63..2344c7ab8fc699 100644 --- a/develop-docs/sdk/telemetry/spans/sampling.mdx +++ b/develop-docs/sdk/telemetry/spans/sampling.mdx @@ -2,6 +2,10 @@ title: Sampling --- + + 🚧 This document is work in progress. + + This document uses key words such as "MUST", "SHOULD", and "MAY" as defined in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) to indicate requirement levels. diff --git a/develop-docs/sdk/telemetry/spans/scrubbing-data.mdx b/develop-docs/sdk/telemetry/spans/scrubbing-data.mdx index 489fd60aad1afa..cdc032c663cd24 100644 --- a/develop-docs/sdk/telemetry/spans/scrubbing-data.mdx +++ b/develop-docs/sdk/telemetry/spans/scrubbing-data.mdx @@ -2,6 +2,10 @@ title: Scrubbing data --- + + 🚧 This document is work in progress. + + This document uses key words such as "MUST", "SHOULD", and "MAY" as defined in [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) to indicate requirement levels.