diff --git a/develop-docs/sdk/telemetry/spans/filtering.mdx b/develop-docs/sdk/telemetry/spans/filtering.mdx new file mode 100644 index 0000000000000..5ef9a8d6223ef --- /dev/null +++ b/develop-docs/sdk/telemetry/spans/filtering.mdx @@ -0,0 +1,53 @@ +--- +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. + + +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/index.mdx b/develop-docs/sdk/telemetry/spans/index.mdx new file mode 100644 index 0000000000000..6853b90e443fd --- /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/sampling.mdx b/develop-docs/sdk/telemetry/spans/sampling.mdx new file mode 100644 index 0000000000000..2344c7ab8fc69 --- /dev/null +++ b/develop-docs/sdk/telemetry/spans/sampling.mdx @@ -0,0 +1,32 @@ +--- +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. + + +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 0000000000000..cdc032c663cd2 --- /dev/null +++ b/develop-docs/sdk/telemetry/spans/scrubbing-data.mdx @@ -0,0 +1,31 @@ +--- +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. + + +## 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.