Skip to content

Commit a3e2613

Browse files
chore(wording): Apply RFC keywords MUST, SHOULD and MAY
1 parent 2204814 commit a3e2613

File tree

1 file changed

+13
-12
lines changed

1 file changed

+13
-12
lines changed

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

Lines changed: 13 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,34 +1,35 @@
11
---
22
title: Span Sampling & Filtering
33
---
4+
45
<Alert level="info">
56
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.
67
</Alert>
78

8-
Any APIs exposed to the user to sample or filter spans must adhere to the following design principles:
9+
Any APIs exposed to the user to sample or filter spans MUST adhere to the following design principles:
910

1011
- The APIs are optimized for trace completeness
1112
- The APIs are optimized for conclusive sampling decisions
1213

1314
## Sample root spans with `tracesSampleRate` & `tracesSampler`
1415

15-
The SDK is automatically initialized with a `tracesSampleRate` of `0`.
16-
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.
16+
The SDK is automatically initialized with a `tracesSampleRate` of `0.0`.
17+
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.
1718

1819
If the SDK is configured with a `tracesSampler`, the `tracesSampleRate` no longer applies.
19-
The `tracesSampler` callback must receive sufficient arguments from users to define their own sampling rules.
20-
This can include but is not limited to certain attributes from the root span, such as HTTP headers.
20+
The `tracesSampler` callback MUST receive sufficient arguments from users to define their own sampling rules.
21+
This MAY include but is not limited to certain attributes from the root span, such as HTTP headers.
2122
The return value of the `tracesSampler` is a float between `0.0` and `1.0`.
2223

23-
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`.
24+
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`.
2425

2526
## Filter spans with `ignoreSpans` & integration config
2627

27-
The SDK must implement a mechanism for users to filter out spans. The result must be binary (true/false).
28+
The SDK MUST implement a mechanism for users to filter out spans. The result MUST be binary (true/false).
2829
The `ignoreSpans` option accepts a glob pattern or string.
29-
The `integrations` option can perform in similar fashion or make explicit opt-out possible via a bool flag.
30+
The `integrations` option MAY perform in similar fashion or make explicit opt-out possible via a bool flag.
3031

31-
If both options are not feasible to be implemented in certain SDKs, other approaches must be explored that have the same outcome.
32+
If both options are not feasible to be implemented in certain SDKs, other approaches MUST be explored that have the same outcome.
3233

3334
```js
3435
Sentry.init({
@@ -50,7 +51,7 @@ Sentry.init({
5051

5152
## Sanitize span attributes with `beforeSendSpans`
5253

53-
This callback must not allow the removal of any spans from the span tree.
54+
This callback MUST NOT allow the removal of any spans from the span tree.
5455
It receives a deep copy of all spans in the span tree and their attributes.
5556

5657
```
@@ -65,5 +66,5 @@ It receives a deep copy of all spans in the span tree and their attributes.
6566
]
6667
```
6768

68-
Users can mutate any exposed properties to perform sanitation on sensitive data or Pii.
69-
The return value `beforeSendSpans` should be merged with the original span tree prior to emission.
69+
Users MAY mutate any exposed properties to perform sanitation on sensitive data or PII.
70+
The return value of `beforeSendSpans` MUST be merged with the original span tree prior to emission.

0 commit comments

Comments
 (0)