sentry-vir 4.3.0 → 4.4.0

package/dist/event-context/event-context.d.ts

@@ -1,5 +1,6 @@
 import { type JsonCompatibleObject, type PartialWithUndefined } from '@augment-vir/common';
 import { type Attachment, type ScopeContext, type setTags } from '@sentry/core';
+import { type RequireOneOrNone } from 'type-fest';
 import { type EventSeverityEnum } from './event-severity.js';
 export type { Attachment } from '@sentry/core';
 /**
@@ -17,12 +18,31 @@ export type EventContextAndTags = PartialWithUndefined<{
     context: EventExtraContext;
     tags: EventTags;
     attachments: ReadonlyArray<Attachment>;
+    /**
+     * Per-event throttle override. At most one of `threshold` / `disabled` may be set: `threshold`
+     * tightens throttling for this event, `disabled` bypasses it entirely.
+     */
+    throttle: ThrottleOverride;
+}>;
+/**
+ * Per-event throttle override carried alongside an event. At most one of `threshold` / `disabled`
+ * may be set on a single override.
+ *
+ * @category Internal
+ */
+export type ThrottleOverride = RequireOneOrNone<{
     /**
      * Per-event throttle threshold override. When set, throttling for this event uses the minimum
      * of this value and the globally-configured `throttleThreshold`, allowing individual log calls
      * to be throttled more aggressively than the global default.
      */
-    throttleThreshold: number;
+    threshold: number;
+    /**
+     * When `true`, this event bypasses the throttle check entirely — it is always forwarded to
+     * Sentry and does not count against its cluster's interval bucket. Useful for important events
+     * that should never be dropped (e.g. critical alerts).
+     */
+    disabled: boolean;
 }>;
 /** Function that generates extra event context. */
 export type EventExtraContextCreator = () => EventExtraContext;

package/dist/event-context/extra-context.error.d.ts

@@ -1,6 +1,6 @@
 import { type Attachment } from '@sentry/core';
-import { type EventContextAndTags, type EventExtraContext, type EventTags } from './event-context.js';
-import { extraEventAttachmentsSymbol, extraEventContextSymbol, extraEventTagsSymbol, extraEventThrottleThresholdSymbol } from './extra-event-context.js';
+import { type EventContextAndTags, type EventExtraContext, type EventTags, type ThrottleOverride } from './event-context.js';
+import { extraEventAttachmentsSymbol, extraEventContextSymbol, extraEventTagsSymbol, extraEventThrottleSymbol } from './extra-event-context.js';
 /**
  * Constructs an error with extra event context attached to it in the same way that
  * throwWithExtraContext attaches data.
@@ -16,7 +16,7 @@ export declare class ExtraContextError extends Error {
     readonly [extraEventContextSymbol]: EventExtraContext | undefined;
     readonly [extraEventTagsSymbol]: EventTags | undefined;
     readonly [extraEventAttachmentsSymbol]: ReadonlyArray<Attachment> | undefined;
-    readonly [extraEventThrottleThresholdSymbol]: number | undefined;
+    readonly [extraEventThrottleSymbol]: ThrottleOverride | undefined;
     constructor(message: string, extraData: EventContextAndTags);
 }
 /**

package/dist/event-context/extra-context.error.js

@@ -1,5 +1,5 @@
 import { ensureError } from '@augment-vir/common';
-import { extraEventAttachmentsSymbol, extraEventContextSymbol, extraEventTagsSymbol, extraEventThrottleThresholdSymbol, } from './extra-event-context.js';
+import { extraEventAttachmentsSymbol, extraEventContextSymbol, extraEventTagsSymbol, extraEventThrottleSymbol, } from './extra-event-context.js';
 /**
  * Constructs an error with extra event context attached to it in the same way that
  * throwWithExtraContext attaches data.
@@ -15,7 +15,7 @@ export class ExtraContextError extends Error {
     [extraEventContextSymbol];
     [extraEventTagsSymbol];
     [extraEventAttachmentsSymbol];
-    [extraEventThrottleThresholdSymbol];
+    [extraEventThrottleSymbol];
     constructor(message, extraData) {
         super(message);
         if (extraData.context) {
@@ -27,8 +27,8 @@ export class ExtraContextError extends Error {
         if (extraData.attachments) {
             this[extraEventAttachmentsSymbol] = extraData.attachments;
         }
-        if (extraData.throttleThreshold != undefined) {
-            this[extraEventThrottleThresholdSymbol] = extraData.throttleThreshold;
+        if (extraData.throttle) {
+            this[extraEventThrottleSymbol] = extraData.throttle;
         }
     }
 }
@@ -47,8 +47,8 @@ export function throwWithExtraContext(originalError, extraData) {
     if (extraData.attachments) {
         error[extraEventAttachmentsSymbol] = extraData.attachments;
     }
-    if (extraData.throttleThreshold != undefined) {
-        error[extraEventThrottleThresholdSymbol] = extraData.throttleThreshold;
+    if (extraData.throttle) {
+        error[extraEventThrottleSymbol] = extraData.throttle;
     }
     throw error;
 }

package/dist/event-context/extra-event-context.d.ts

@@ -1,5 +1,5 @@
 import { type Attachment, type Event, type EventHint } from '@sentry/core';
-import { type EventExtraContext, type EventTags } from './event-context.js';
+import { type EventExtraContext, type EventTags, type ThrottleOverride } from './event-context.js';
 /**
  * Symbol used to attach extra event context to events. This is particularly useful for errors so
  * they can be thrown while attaching this extra context to them.
@@ -16,10 +16,11 @@ export declare const extraEventTagsSymbol: unique symbol;
  */
 export declare const extraEventAttachmentsSymbol: unique symbol;
 /**
- * Symbol used to attach a per-event throttle threshold override. When present, throttling uses the
- * minimum of this value and the globally-configured `throttleThreshold`.
+ * Symbol used to attach a per-event throttle override to an event or error. The attached value is a
+ * {@link ThrottleOverride}: at most one of `threshold` (tighten throttling for this event) or
+ * `disabled` (bypass throttling entirely) may be set.
  */
-export declare const extraEventThrottleThresholdSymbol: unique symbol;
+export declare const extraEventThrottleSymbol: unique symbol;
 /** Simply describes an object that has extra event context. */
 export type HasExtraContext = {
     [extraEventContextSymbol]: EventExtraContext;
@@ -32,9 +33,9 @@ export type HasExtraTags = {
 export type HasExtraAttachments = {
     [extraEventAttachmentsSymbol]: ReadonlyArray<Attachment>;
 };
-/** Simply describes an object that has a per-event throttle threshold override. */
-export type HasExtraThrottleThreshold = {
-    [extraEventThrottleThresholdSymbol]: number;
+/** Simply describes an object that carries a per-event throttle override. */
+export type HasExtraThrottle = {
+    [extraEventThrottleSymbol]: ThrottleOverride;
 };
 /** Type guard for whether any given input has extra event context. */
 export declare function hasExtraEventContext(input: unknown): input is HasExtraContext;
@@ -42,8 +43,8 @@ export declare function hasExtraEventContext(input: unknown): input is HasExtraC
 export declare function hasExtraEventTags(input: unknown): input is HasExtraTags;
 /** Type guard for whether any given input has extra event attachments. */
 export declare function hasExtraEventAttachments(input: unknown): input is HasExtraAttachments;
-/** Type guard for whether any given input carries a per-event throttle threshold override. */
-export declare function hasExtraEventThrottleThreshold(input: unknown): input is HasExtraThrottleThreshold;
+/** Type guard for whether any given input carries a per-event throttle override. */
+export declare function hasExtraEventThrottle(input: unknown): input is HasExtraThrottle;
 /**
  * Checks if extra event context has been injected into the input via extraEventContextSymbol and,
  * if so, extracts it.
@@ -75,7 +76,7 @@ export declare function extractExtraEventTags(event: EventHint | Event): EventTa
  */
 export declare function extractExtraEventAttachments(event: EventHint | Event): ReadonlyArray<Attachment> | undefined;
 /**
- * Tries to extract a per-event throttle threshold via extraEventThrottleThresholdSymbol from the
- * input itself or its originalException. Returns undefined if none is set.
+ * Tries to extract a per-event {@link ThrottleOverride} via extraEventThrottleSymbol from the input
+ * itself or its originalException. Returns `undefined` if none is set.
  */
-export declare function extractExtraEventThrottleThreshold(event: EventHint | Event): number | undefined;
+export declare function extractExtraEventThrottle(event: EventHint | Event): ThrottleOverride | undefined;

package/dist/event-context/extra-event-context.js

@@ -15,10 +15,11 @@ export const extraEventTagsSymbol = Symbol('extra-event-tags');
  */
 export const extraEventAttachmentsSymbol = Symbol('extra-event-attachments');
 /**
- * Symbol used to attach a per-event throttle threshold override. When present, throttling uses the
- * minimum of this value and the globally-configured `throttleThreshold`.
+ * Symbol used to attach a per-event throttle override to an event or error. The attached value is a
+ * {@link ThrottleOverride}: at most one of `threshold` (tighten throttling for this event) or
+ * `disabled` (bypass throttling entirely) may be set.
  */
-export const extraEventThrottleThresholdSymbol = Symbol('extra-event-throttle-threshold');
+export const extraEventThrottleSymbol = Symbol('extra-event-throttle');
 /** Type guard for whether any given input has extra event context. */
 export function hasExtraEventContext(input) {
     return check.hasKey(input, extraEventContextSymbol) && !!input[extraEventContextSymbol];
@@ -31,10 +32,9 @@ export function hasExtraEventTags(input) {
 export function hasExtraEventAttachments(input) {
     return check.hasKey(input, extraEventAttachmentsSymbol) && !!input[extraEventAttachmentsSymbol];
 }
-/** Type guard for whether any given input carries a per-event throttle threshold override. */
-export function hasExtraEventThrottleThreshold(input) {
-    return (check.hasKey(input, extraEventThrottleThresholdSymbol) &&
-        check.isNumber(input[extraEventThrottleThresholdSymbol]));
+/** Type guard for whether any given input carries a per-event throttle override. */
+export function hasExtraEventThrottle(input) {
+    return check.hasKey(input, extraEventThrottleSymbol) && !!input[extraEventThrottleSymbol];
 }
 /**
  * Checks if extra event context has been injected into the input via extraEventContextSymbol and,
@@ -133,15 +133,13 @@ export function extractExtraEventAttachments(event) {
     }
 }
 /**
- * Tries to extract a per-event throttle threshold via extraEventThrottleThresholdSymbol from the
- * input itself or its originalException. Returns undefined if none is set.
+ * Tries to extract a per-event {@link ThrottleOverride} via extraEventThrottleSymbol from the input
+ * itself or its originalException. Returns `undefined` if none is set.
  */
-export function extractExtraEventThrottleThreshold(event) {
-    const fromRoot = hasExtraEventThrottleThreshold(event)
-        ? event[extraEventThrottleThresholdSymbol]
-        : undefined;
-    const fromException = 'originalException' in event && hasExtraEventThrottleThreshold(event.originalException)
-        ? event.originalException[extraEventThrottleThresholdSymbol]
+export function extractExtraEventThrottle(event) {
+    const fromRoot = hasExtraEventThrottle(event) ? event[extraEventThrottleSymbol] : undefined;
+    const fromException = 'originalException' in event && hasExtraEventThrottle(event.originalException)
+        ? event.originalException[extraEventThrottleSymbol]
         : undefined;
     return fromRoot ?? fromException;
 }

package/dist/logging/handle-error.js

@@ -1,7 +1,7 @@
 import { extractErrorMessage } from '@augment-vir/common';
 import { convertEventDetailsToSentryContext, } from '../event-context/event-context.js';
 import { EventSeverityEnum } from '../event-context/event-severity.js';
-import { extractExtraAttachmentsFromSymbol, extractExtraEventThrottleThreshold, } from '../event-context/extra-event-context.js';
+import { extractExtraAttachmentsFromSymbol, extractExtraEventThrottle, extractExtraTagsFromSymbol, } from '../event-context/extra-event-context.js';
 import { LoggingState, logToConsoleWithoutSentry } from '../processing/log-to-console.js';
 import { skipBeforeSendThrottleContextKey } from '../processing/throttling.js';
 import { addPrematureEvent } from './premature-events.js';
@@ -32,21 +32,37 @@ function internalHandleError(error, eventOptions, options) {
             ]);
             return undefined;
         }
-        const perCallThresholdCandidates = [
-            extractExtraEventThrottleThreshold({
-                originalException: error,
-            }),
-            eventOptions?.throttleThreshold,
-        ].filter((value) => value != undefined);
-        const perCallThrottleThreshold = perCallThresholdCandidates.length
-            ? Math.min(...perCallThresholdCandidates)
-            : undefined;
-        if (checkActiveThrottle({
-            message: extractErrorMessage(error),
-        }, {
+        const errorThrottleOverride = extractExtraEventThrottle({
             originalException: error,
-        }, perCallThrottleThreshold)) {
-            return undefined;
+        });
+        const disableThrottling = eventOptions?.throttle?.disabled === true || errorThrottleOverride?.disabled === true;
+        if (!disableThrottling) {
+            const perCallThresholdCandidates = [
+                errorThrottleOverride?.threshold,
+                eventOptions?.throttle?.threshold,
+            ].filter((value) => value != undefined);
+            const perCallThrottleThreshold = perCallThresholdCandidates.length
+                ? Math.min(...perCallThresholdCandidates)
+                : undefined;
+            const symbolTags = extractExtraTagsFromSymbol(error);
+            const combinedTags = symbolTags == undefined && eventOptions?.tags == undefined
+                ? undefined
+                : {
+                    ...symbolTags,
+                    ...eventOptions?.tags,
+                };
+            if (checkActiveThrottle({
+                message: extractErrorMessage(error),
+                ...(combinedTags
+                    ? {
+                        tags: combinedTags,
+                    }
+                    : {}),
+            }, {
+                originalException: error,
+            }, perCallThrottleThreshold)) {
+                return undefined;
+            }
         }
         const scopeContext = convertEventDetailsToSentryContext({
             extraContext: eventOptions?.context,

package/dist/logging/send-log.d.ts

@@ -1,6 +1,6 @@
 import { type PartialWithUndefined } from '@augment-vir/common';
 import { type ErrorEvent, type EventHint, type Event as SentryEvent, type TransactionEvent } from '@sentry/core';
-import { type ContextOptions, type EventContextAndTags, type EventDetails } from '../event-context/event-context.js';
+import { type ContextOptions, type EventContextAndTags, type EventDetails, type ThrottleOverride } from '../event-context/event-context.js';
 import { type ThrottleOptions } from '../processing/throttling.js';
 /** A Sentry event object without the fields that are set by the logging context. */
 export type SendLogEvent = Omit<SentryEvent, 'extra' | 'level'>;
@@ -23,7 +23,7 @@ export declare const sendLog: {
  *
  * @category Internal
  */
-export declare function throttleEventWithLogging(event: Pick<TransactionEvent | ErrorEvent, 'message'>, hint: Readonly<Pick<EventHint, 'originalException'>> | undefined, options: Readonly<PartialWithUndefined<ThrottleOptions>>): boolean;
+export declare function throttleEventWithLogging(event: Pick<TransactionEvent | ErrorEvent, 'message' | 'tags'>, hint: Readonly<Pick<EventHint, 'originalException'>> | undefined, options: Readonly<PartialWithUndefined<ThrottleOptions>>): boolean;
 /**
  * Synchronous pre-capture throttle check used by `sendLog` and `handleError`. Returns `true` when
  * the event should be dropped. Returns `false` (i.e. "send it") when no active throttle options
@@ -31,6 +31,6 @@ export declare function throttleEventWithLogging(event: Pick<TransactionEvent |
  *
  * @category Internal
  */
-export declare function checkActiveThrottle(event: Pick<TransactionEvent | ErrorEvent, 'message'>, hint: Readonly<Pick<EventHint, 'originalException'>> | undefined, perCallThreshold: number | undefined): boolean;
-declare function sendLogToSentry(logInfo: SendLogInfo, eventDetails: EventDetails, options: ContextOptions, perCallThrottleThreshold: number | undefined): string | undefined;
+export declare function checkActiveThrottle(event: Pick<TransactionEvent | ErrorEvent, 'message' | 'tags'>, hint: Readonly<Pick<EventHint, 'originalException'>> | undefined, perCallThreshold: number | undefined): boolean;
+declare function sendLogToSentry(logInfo: SendLogInfo, eventDetails: EventDetails, options: ContextOptions, perCallThrottle: ThrottleOverride | undefined): string | undefined;
 export {};

package/dist/logging/send-log.js

@@ -28,14 +28,16 @@ export function throttleEventWithLogging(event, hint, options) {
     const result = shouldThrottleEvent(event, hint, options);
     const disableLog = options.disableThrottleLog ?? defaultThrottleOptions.disableThrottleLog;
     if (!disableLog && result.errorKey != undefined) {
+        const inheritedTags = {
+            ...event.tags,
+            suppressedErrorKey: result.errorKey,
+        };
         if (result.transition.kind === 'started') {
             sendLog.warning(`Throttling started: ${result.errorKey}`, {
                 context: {
                     suppressedErrorKey: result.errorKey,
                 },
-                tags: {
-                    suppressedErrorKey: result.errorKey,
-                },
+                tags: inheritedTags,
             });
         }
         else if (result.transition.kind === 'ended') {
@@ -44,9 +46,7 @@ export function throttleEventWithLogging(event, hint, options) {
                     suppressedErrorKey: result.errorKey,
                     suppressedCount: result.transition.suppressedCount,
                 },
-                tags: {
-                    suppressedErrorKey: result.errorKey,
-                },
+                tags: inheritedTags,
             });
         }
     }
@@ -75,10 +75,10 @@ function wrapLogWithSeverity(severity) {
             severity,
         }, {
             wasSentPrematurely: false,
-        }, eventOptions?.throttleThreshold);
+        }, eventOptions?.throttle);
     };
 }
-function sendLogToSentry(logInfo, eventDetails, options, perCallThrottleThreshold) {
+function sendLogToSentry(logInfo, eventDetails, options, perCallThrottle) {
     try {
         /**
          * `Error.message` is not enumerable, so spreading an `Error` into `captureEvent` would lose
@@ -102,17 +102,24 @@ function sendLogToSentry(logInfo, eventDetails, options, perCallThrottleThreshol
                 {
                     wasSentPrematurely: true,
                 },
-                perCallThrottleThreshold,
+                perCallThrottle,
             ]);
             return undefined;
         }
-        const throttleMessage = check.isString(resolvedLogInfo)
-            ? resolvedLogInfo
-            : extractOriginalMessage(resolvedLogInfo, undefined);
-        if (checkActiveThrottle({
-            message: throttleMessage,
-        }, undefined, perCallThrottleThreshold)) {
-            return undefined;
+        if (perCallThrottle?.disabled !== true) {
+            const throttleMessage = check.isString(resolvedLogInfo)
+                ? resolvedLogInfo
+                : extractOriginalMessage(resolvedLogInfo, undefined);
+            if (checkActiveThrottle({
+                message: throttleMessage,
+                ...(eventDetails.tags
+                    ? {
+                        tags: eventDetails.tags,
+                    }
+                    : {}),
+            }, undefined, perCallThrottle?.threshold)) {
+                return undefined;
+            }
         }
         const scopeContext = convertEventDetailsToSentryContext(eventDetails, options);
         const client = sentryClientForLogging;

package/dist/processing/handle-sentry-send.js

@@ -1,4 +1,4 @@
-import { extractExtraEventThrottleThreshold } from '../event-context/extra-event-context.js';
+import { extractExtraEventThrottle } from '../event-context/extra-event-context.js';
 import { throttleEventWithLogging } from '../logging/send-log.js';
 import { LoggingState, logToConsoleFromSentry } from './log-to-console.js';
 import { combineThrottleThreshold, skipBeforeSendThrottleContextKey, } from './throttling.js';
@@ -14,11 +14,11 @@ export function createSentryHandler({ isDev, isSilent, throttleOptions, }) {
         if (event.contexts && skipBeforeSendThrottleContextKey in event.contexts) {
             delete event.contexts[skipBeforeSendThrottleContextKey];
         }
-        if (!wasPreThrottled) {
-            const perEventThreshold = extractExtraEventThrottleThreshold(hint);
-            if (throttleEventWithLogging(event, hint, combineThrottleThreshold(throttleOptions, perEventThreshold))) {
-                return null;
-            }
+        const eventThrottleOverride = extractExtraEventThrottle(hint);
+        if (!wasPreThrottled &&
+            eventThrottleOverride?.disabled !== true &&
+            throttleEventWithLogging(event, hint, combineThrottleThreshold(throttleOptions, eventThrottleOverride?.threshold))) {
+            return null;
         }
         if (!event.extra?.wasSentPrematurely) {
             logToConsoleFromSentry(event, hint, isDev ? LoggingState.Dev : LoggingState.Prod, isSilent);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "sentry-vir",
-    "version": "4.3.0",
+    "version": "4.4.0",
     "description": "Easily use Sentry.",
     "keywords": [
         "config",