Span Sampling & Filtering

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.

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.

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.

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.