From 6913cf50e59ca248ada978b7535c11e9d566d18b Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Wed, 6 Aug 2025 17:07:58 +0200 Subject: [PATCH 1/3] ref(spans): Expand `ignoreSpans` type and implementation specification --- .../sdk/telemetry/spans/filtering.mdx | 34 ++++++++++++++++++- 1 file changed, 33 insertions(+), 1 deletion(-) diff --git a/develop-docs/sdk/telemetry/spans/filtering.mdx b/develop-docs/sdk/telemetry/spans/filtering.mdx index cb7ba442d775e5..f3c7f318e638de 100644 --- a/develop-docs/sdk/telemetry/spans/filtering.mdx +++ b/develop-docs/sdk/telemetry/spans/filtering.mdx @@ -19,16 +19,48 @@ Any APIs exposed to the user to filter spans MUST adhere to the following design ## Filter with `ignoreSpans` -The `ignoreSpans` option accepts a glob pattern or string. +The `ignoreSpans` option MUST accept a string, RegExp or glob pattern (whichever of the two the platform supports). Furthermore, it SHOULD accept an Object with the patterns matching at least one of or both, the span name and op. + +```ts +type IgnoreSpanPattern = string | RegExp | GlobPattern; + +type IgnoreSpanFilter = { + name: IgnoreSpanPattern; + op?: IgnoreSpanPattern; +} | { + name?: IgnoreSpanPattern; + op: IgnoreSpanPattern; +} + +type IgnoreSpans = Array +``` +(Note: `GlobPattern` is used as an illustrative type. It is not a valid TypeScript type.) + +Example: ```js Sentry.init({ ignoreSpans: [ 'GET /about', 'events.signal *', + /api\/\d+/, + { + op: 'fs.read', + }, + { + name: 'health', + op: 'http.client', + } ] }) ``` +(Note: The glob pattern serves an illustrative purpose. It is not supported in JavaScript.) + +### Implementation Requirements + +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. ## Filter with `integrations` From 35eb5f2e52964cbfd62dc08f0aaaac0682772e32 Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Wed, 6 Aug 2025 17:12:10 +0200 Subject: [PATCH 2/3] regexp in object --- develop-docs/sdk/telemetry/spans/filtering.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/develop-docs/sdk/telemetry/spans/filtering.mdx b/develop-docs/sdk/telemetry/spans/filtering.mdx index f3c7f318e638de..a3605d57c38618 100644 --- a/develop-docs/sdk/telemetry/spans/filtering.mdx +++ b/develop-docs/sdk/telemetry/spans/filtering.mdx @@ -48,7 +48,7 @@ Sentry.init({ op: 'fs.read', }, { - name: 'health', + name: /healthz?/, op: 'http.client', } ] From 890aba76bef82298e9865ffd5813b672817bf657 Mon Sep 17 00:00:00 2001 From: Lukas Stracke Date: Tue, 12 Aug 2025 17:15:21 +0200 Subject: [PATCH 3/3] switch to attribute matching instead of op --- .../sdk/telemetry/spans/filtering.mdx | 56 ++++++++++++++----- 1 file changed, 41 insertions(+), 15 deletions(-) diff --git a/develop-docs/sdk/telemetry/spans/filtering.mdx b/develop-docs/sdk/telemetry/spans/filtering.mdx index a3605d57c38618..71333ec635a204 100644 --- a/develop-docs/sdk/telemetry/spans/filtering.mdx +++ b/develop-docs/sdk/telemetry/spans/filtering.mdx @@ -19,48 +19,74 @@ Any APIs exposed to the user to filter spans MUST adhere to the following design ## Filter with `ignoreSpans` -The `ignoreSpans` option MUST accept a string, RegExp or glob pattern (whichever of the two the platform supports). Furthermore, it SHOULD accept an Object with the patterns matching at least one of or both, the span name and op. +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 IgnoreSpanPattern = string | RegExp | GlobPattern; +type IgnoreSpanNamePattern = string | RegExp | GlobPattern; + +// all allowed values for span attributes (unlikely but could differ by platform) +type AttributeValueTypes = string | boolean | number | Array | Array | Array; +type EnhancedAttributeValueTypes = AttributeValueTypes | RegExp | GlobPattern; type IgnoreSpanFilter = { - name: IgnoreSpanPattern; - op?: IgnoreSpanPattern; + name: IgnoreSpanNamePattern; + attributes?: Record; } | { - name?: IgnoreSpanPattern; - op: IgnoreSpanPattern; + name?: IgnoreSpanNamePattern; + attributes?: Record; } -type IgnoreSpans = Array +type IgnoreSpans = Array ``` -(Note: `GlobPattern` is used as an illustrative type. It is not a valid TypeScript type.) +(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) { - op: 'fs.read', + attributes: { + 'http.method': /GET \/api\/.*/, + 'http.status_code': 200, + } }, + // ignore all spans with name starting with /imprint- + // if glob patterns are supported { - name: /healthz?/, - op: 'http.client', + name: '/imprint-*' } ] }) ``` -(Note: The glob pattern serves an illustrative purpose. It is not supported in JavaScript.) +(Note: The glob patterns used in the example serve an illustrative purpose. They are not supported in JavaScript.) ### Implementation Requirements -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. +1. 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. + +2. If SDKs accept `IgnoreSpanFilter` objects, attributes MUST be matched by value. This also applies to attributes with array values. + - 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. + ## Filter with `integrations`