---
title: "Filtering"
url: https://develop.sentry.dev/sdk/telemetry/spans/filtering/
---

# 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`](https://develop.sentry.dev/sdk/telemetry/spans/filtering.md#filter-with-ignorespans)

The `ignoreSpans` option MUST accept a string, RegExp or glob pattern (whichever of the two the platform supports). These values MUST be matched against the span name.

Furthermore, `ignoreSpans` SHOULD accept an Object with patterns matching the span name, or span attributes (see type definitions below).

```ts
type IgnoreSpanNamePattern = string | RegExp | GlobPattern;

// all allowed values for span attributes (unlikely but could differ by platform)
type AttributeValueTypes = string | boolean | number | Array<string> | Array<boolean> | Array<number>;
type EnhancedAttributeValueTypes = AttributeValueTypes | RegExp | GlobPattern;

type IgnoreSpanFilter = {
  name: IgnoreSpanNamePattern;
  attributes?: Record<string, EnhancedAttributeValueTypes>;
} | {
  name?: IgnoreSpanNamePattern;
  attributes?: Record<string, EnhancedAttributeValueTypes>;
}

type IgnoreSpans = Array<IgnoreSpanNamePattern | IgnoreSpanFilter>
```

(Note: `GlobPattern` is used as an illustrative type for platforms that support matching glob patterns. It is not a valid TypeScript type.)

Example:

```js
Sentry.init({
  ignoreSpans: [
    // apply on span name
    'GET /about',
    'events.signal *',
    /api\/\d+/,
    // ignore health check GET requests with 200 status code
    {
      name: /healthz?/,
      attributes: {
        'http.method': 'GET',
        'http.status_code': 200,
      }
    },
    // ignore all GET requests to /api/ with 200 status code 
    // (i.e. span name doesn't matter)
    {
      attributes: {
        'http.method': /GET \/api\/.*/,
        'http.status_code': 200,
      }
    },
    // ignore all spans with name starting with /imprint-
    // if glob patterns are supported
    {
      name: '/imprint-*'
    }
  ]
})
```

(Note: The glob patterns used in the example serve an illustrative purpose. They are not supported in JavaScript.)

### [Implementation Requirements](https://develop.sentry.dev/sdk/telemetry/spans/filtering.md#implementation-requirements)

1. The `ignoreSpans` patterns MUST be evaluated **before** the span is started.

2. The `ignoreSpans` patterns MUST be applied to all spans, including the root or segment span.

   * If a pattern matches the root span, the span and all its children MUST be ignored.
   * If a pattern matches a child span, the span MUST be ignored but any potential child spans MUST be attempted to be reparented to the parent span of the ignored span.

3. If an SDK accepts `IgnoreSpanFilter` objects, span attributes must be matched by their exact value. This includes attributes whose values are arrays.

   * String attribute values are matched in the same fashion as span names: If a string is provided, the string MUST match (contains), if a `RegExp` or glob pattern is provided, the value MUST match the pattern.
   * Any other attribute value type MUST strictly equal the provided value.

4. If a span is ignored, the SDK **MUST** record a client report with the `ignored` discard reason and `span` category for the span.

   * For each ignored child span, emit one outcome per span
   * For each ignored segment span, emit one outcome for the segment and one for each child span (which are all ignored due to the segment being ignored)

## [Filter with `integrations`](https://develop.sentry.dev/sdk/telemetry/spans/filtering.md#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](https://develop.sentry.dev/sdk/telemetry/spans/filtering.md#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.