docs(sdks): Span Sampling (#11940)

* docs(sdks): Span Sampling

* Remove out-of-scope items

* chore(wording): Apply RFC keywords MUST, SHOULD and MAY

* chore(docs): split contents into separate files

* chore(docs): indicate work in progress

---------

Co-authored-by: Stephanie Anderson <[email protected]>

Author: cleptric

develop-docs/sdk/telemetry/spans/filtering.mdx

@@ -0,0 +1,53 @@
+---
+title: Filtering
+---
+
+<Alert level="warning">
+  🚧 This document is work in progress.
+</Alert>
+
+<Alert level="info">
+  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.
+</Alert>
+
+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.

develop-docs/sdk/telemetry/spans/index.mdx

@@ -0,0 +1,6 @@
+---
+title: Spans
+sidebar_order: 8
+---
+
+<PageGrid />

develop-docs/sdk/telemetry/spans/sampling.mdx

@@ -0,0 +1,32 @@
+---
+title: Sampling
+---
+
+<Alert level="warning">
+  🚧 This document is work in progress.
+</Alert>
+
+<Alert level="info">
+  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.
+</Alert>
+
+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`.

develop-docs/sdk/telemetry/spans/scrubbing-data.mdx

@@ -0,0 +1,31 @@
+---
+title: Scrubbing data
+---
+
+<Alert level="warning">
+  🚧 This document is work in progress.
+</Alert>
+
+<Alert level="info">
+  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.
+</Alert>
+
+## 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.