feat: add classifyError callback for error severity control

README.md

@@ -71,6 +71,7 @@ All options are passed to `init()` as an `ObservabilityConfig` object.
 | `otlp` | `OtlpConfig` | — | OTLP trace export configuration. See below. |
 | `filters` | `FilterConfig` | — | Filtering rules for traces, errors, and breadcrumbs. See below. |
 | `shouldDropError` | `(error: unknown) => boolean` | — | Predicate to suppress specific errors from Sentry. Return `true` to drop. |
+| `classifyError` | `(error: unknown) => 'drop' \| 'warning' \| undefined` | — | Classify errors before sending to Sentry. `'drop'` suppresses the error, `'warning'` downgrades its severity level, `undefined` leaves it unchanged. |
 
 ### `SentryConfig`
 
@@ -126,6 +127,10 @@ init({
   },
   shouldDropError: (error) =>
     error instanceof MyClientError && error.code === 'NOT_FOUND',
+  classifyError: (error) => {
+    if (error instanceof TransportError && error.transient) return 'warning'
+    return undefined
+  },
 })
 ```
 
@@ -282,6 +287,7 @@ When the consuming application (e.g. `agentic-api`) calls `init({ enableOtel: tr
 Several things happen without any additional configuration:
 
 - **`JWTExpired` errors are silently dropped** from Sentry — expired tokens are expected and not actionable.
+- **Error classification runs in order**: `shouldDropError` is checked first, then `classifyError`, then the built-in `JWTExpired` filter. The first match wins.
 - **Pyroscope initialization failures are caught** — if Pyroscope fails to start, the error is reported to Sentry and the process continues normally.
 - **Pyroscope and PostHog breadcrumbs are filtered** from Sentry by default via `filters.ignoredBreadcrumbPatterns`.
 - **Test environments are inert** — when `NODE_ENV=test`, `init()` resolves the config but skips all instrumentation. No Sentry, no Pyroscope, no OTel side effects.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@scope3data/observability-js",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Unified observability (Sentry, OpenTelemetry, Pyroscope) for Node.js services",
   "keywords": [
     "observability",

src/__tests__/filtering.test.ts

@@ -108,6 +108,54 @@ describe('Observability Filtering', () => {
     })
   })
 
+  describe('classifyError callback pattern', () => {
+    class TransportError extends Error {
+      constructor(
+        message: string,
+        public readonly transient: boolean,
+      ) {
+        super(message)
+        this.name = 'TransportError'
+      }
+    }
+
+    const classifyError = (error: unknown): 'drop' | 'warning' | undefined => {
+      if (error instanceof TransportError) {
+        return error.transient ? 'warning' : undefined
+      }
+      if (
+        error instanceof Error &&
+        error.message.includes('client disconnected')
+      ) {
+        return 'drop'
+      }
+      return undefined
+    }
+
+    it('returns drop to suppress errors', () => {
+      expect(classifyError(new Error('client disconnected unexpectedly'))).toBe(
+        'drop',
+      )
+    })
+
+    it('returns warning to downgrade severity', () => {
+      expect(classifyError(new TransportError('timeout', true))).toBe('warning')
+    })
+
+    it('returns undefined to leave errors unchanged', () => {
+      expect(
+        classifyError(new TransportError('connection refused', false)),
+      ).toBeUndefined()
+      expect(classifyError(new Error('unexpected failure'))).toBeUndefined()
+    })
+
+    it('handles non-Error values gracefully', () => {
+      expect(classifyError(undefined)).toBeUndefined()
+      expect(classifyError(null)).toBeUndefined()
+      expect(classifyError('string error')).toBeUndefined()
+    })
+  })
+
   describe('beforeBreadcrumb logic', () => {
     type MockBreadcrumb = {
       category?: string

src/config.ts

@@ -84,6 +84,7 @@ export function resolveConfig(config: ObservabilityConfig): ResolvedConfig {
     },
 
     shouldDropError: config.shouldDropError,
+    classifyError: config.classifyError,
   }
 
   return resolvedConfig

src/provider.ts

@@ -109,6 +109,15 @@ function initializeSentry(config: ResolvedConfig): void {
         return null
       }
 
+      const classification = config.classifyError?.(error)
+      if (classification === 'drop') {
+        return null
+      }
+      if (classification === 'warning') {
+        event.level = 'warning'
+        return event
+      }
+
       if (error instanceof joseErrors.JWTExpired) {
         return null
       }

src/types.ts

@@ -132,6 +132,13 @@ export interface ObservabilityConfig {
    * Return `true` to drop the error, `false` to allow it through.
    */
   shouldDropError?: (error: unknown) => boolean
+
+  /**
+   * Optional callback to classify errors before they are sent to Sentry.
+   * Return `'drop'` to suppress the error, `'warning'` to downgrade its
+   * severity level, or `undefined` to leave it unchanged.
+   */
+  classifyError?: (error: unknown) => 'drop' | 'warning' | undefined
 }
 
 export interface ResolvedConfig {
@@ -173,6 +180,7 @@ export interface ResolvedConfig {
   }
 
   shouldDropError?: (error: unknown) => boolean
+  classifyError?: (error: unknown) => 'drop' | 'warning' | undefined
 }
 
 /** Context fields attached to MCP tool spans and error reports. */