sentry-vir 4.2.0 → 4.3.0

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

@@ -17,6 +17,12 @@ export type EventContextAndTags = PartialWithUndefined<{
     context: EventExtraContext;
     tags: EventTags;
     attachments: ReadonlyArray<Attachment>;
+    /**
+     * 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;
 }>;
 /** 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 } from './extra-event-context.js';
+import { extraEventAttachmentsSymbol, extraEventContextSymbol, extraEventTagsSymbol, extraEventThrottleThresholdSymbol } from './extra-event-context.js';
 /**
  * Constructs an error with extra event context attached to it in the same way that
  * throwWithExtraContext attaches data.
@@ -16,6 +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;
     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, } from './extra-event-context.js';
+import { extraEventAttachmentsSymbol, extraEventContextSymbol, extraEventTagsSymbol, extraEventThrottleThresholdSymbol, } from './extra-event-context.js';
 /**
  * Constructs an error with extra event context attached to it in the same way that
  * throwWithExtraContext attaches data.
@@ -15,6 +15,7 @@ export class ExtraContextError extends Error {
     [extraEventContextSymbol];
     [extraEventTagsSymbol];
     [extraEventAttachmentsSymbol];
+    [extraEventThrottleThresholdSymbol];
     constructor(message, extraData) {
         super(message);
         if (extraData.context) {
@@ -26,6 +27,9 @@ export class ExtraContextError extends Error {
         if (extraData.attachments) {
             this[extraEventAttachmentsSymbol] = extraData.attachments;
         }
+        if (extraData.throttleThreshold != undefined) {
+            this[extraEventThrottleThresholdSymbol] = extraData.throttleThreshold;
+        }
     }
 }
 /**
@@ -43,5 +47,8 @@ export function throwWithExtraContext(originalError, extraData) {
     if (extraData.attachments) {
         error[extraEventAttachmentsSymbol] = extraData.attachments;
     }
+    if (extraData.throttleThreshold != undefined) {
+        error[extraEventThrottleThresholdSymbol] = extraData.throttleThreshold;
+    }
     throw error;
 }

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

@@ -15,6 +15,11 @@ export declare const extraEventTagsSymbol: unique symbol;
  * for attaching file data to thrown errors.
  */
 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`.
+ */
+export declare const extraEventThrottleThresholdSymbol: unique symbol;
 /** Simply describes an object that has extra event context. */
 export type HasExtraContext = {
     [extraEventContextSymbol]: EventExtraContext;
@@ -27,12 +32,18 @@ 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;
+};
 /** Type guard for whether any given input has extra event context. */
 export declare function hasExtraEventContext(input: unknown): input is HasExtraContext;
 /** Type guard for whether any given input has extra event tags. */
 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;
 /**
  * Checks if extra event context has been injected into the input via extraEventContextSymbol and,
  * if so, extracts it.
@@ -63,3 +74,8 @@ export declare function extractExtraEventTags(event: EventHint | Event): EventTa
  * there are no extra event attachments.
  */
 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.
+ */
+export declare function extractExtraEventThrottleThreshold(event: EventHint | Event): number | undefined;

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

@@ -14,6 +14,11 @@ export const extraEventTagsSymbol = Symbol('extra-event-tags');
  * for attaching file data to thrown errors.
  */
 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`.
+ */
+export const extraEventThrottleThresholdSymbol = Symbol('extra-event-throttle-threshold');
 /** Type guard for whether any given input has extra event context. */
 export function hasExtraEventContext(input) {
     return check.hasKey(input, extraEventContextSymbol) && !!input[extraEventContextSymbol];
@@ -26,6 +31,11 @@ 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]));
+}
 /**
  * Checks if extra event context has been injected into the input via extraEventContextSymbol and,
  * if so, extracts it.
@@ -122,3 +132,16 @@ export function extractExtraEventAttachments(event) {
         return undefined;
     }
 }
+/**
+ * Tries to extract a per-event throttle threshold via extraEventThrottleThresholdSymbol 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]
+        : undefined;
+    return fromRoot ?? fromException;
+}

package/dist/init-sentry/base-sentry-init.js

@@ -1,5 +1,6 @@
 import { setSentryClientForLogging } from '../logging/sentry-client-for-logging.js';
 import { processSentryEvent } from '../processing/event-processor.js';
+import { setActiveThrottleOptions } from '../processing/throttling.js';
 import { createSentryConfig } from './sentry-config.js';
 /**
  * Base Sentry init. Requires the Sentry module to already have been imported. Setup a sentry client
@@ -25,6 +26,7 @@ export async function baseInitSentry({ dsn, releaseEnv, releaseName, sentryConfi
     });
     sentryDep.init(finalSentryConfig);
     sentryDep.addEventProcessor((event, hint) => processSentryEvent(event, hint, createUniversalContext));
+    setActiveThrottleOptions(throttleOptions);
     void setSentryClientForLogging(sentryDep);
     return sentryDep;
 }

package/dist/logging/handle-error.js

@@ -1,9 +1,11 @@
 import { extractErrorMessage } from '@augment-vir/common';
 import { convertEventDetailsToSentryContext, } from '../event-context/event-context.js';
 import { EventSeverityEnum } from '../event-context/event-severity.js';
-import { extractExtraAttachmentsFromSymbol } from '../event-context/extra-event-context.js';
+import { extractExtraAttachmentsFromSymbol, extractExtraEventThrottleThreshold, } 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';
+import { checkActiveThrottle } from './send-log.js';
 import { sentryClientForLogging } from './sentry-client-for-logging.js';
 /** Record an error to Sentry without throwing it. */
 export function handleError(error, eventOptions) {
@@ -30,6 +32,22 @@ 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),
+        }, {
+            originalException: error,
+        }, perCallThrottleThreshold)) {
+            return undefined;
+        }
         const scopeContext = convertEventDetailsToSentryContext({
             extraContext: eventOptions?.context,
             tags: eventOptions?.tags,
@@ -40,14 +58,15 @@ function internalHandleError(error, eventOptions, options) {
             ...(eventOptions?.attachments || []),
             ...(extractExtraAttachmentsFromSymbol(error) || []),
         ];
-        const eventId = allAttachments.length
-            ? client.withScope((scope) => {
-                allAttachments.forEach((attachment) => {
-                    scope.addAttachment(attachment);
-                });
-                return client.captureException(error, scopeContext);
-            })
-            : client.captureException(error, scopeContext);
+        const eventId = client.withScope((scope) => {
+            scope.setContext(skipBeforeSendThrottleContextKey, {
+                skipThrottle: true,
+            });
+            allAttachments.forEach((attachment) => {
+                scope.addAttachment(attachment);
+            });
+            return client.captureException(error, scopeContext);
+        });
         return eventId;
     }
     catch (caught) {

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

@@ -1,5 +1,7 @@
-import { type Event as SentryEvent } from '@sentry/core';
+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 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'>;
 /** All accepted input types for `sendLog`. Strings, Error objects, and raw Sentry events. */
@@ -13,5 +15,22 @@ export declare const sendLog: {
     /** Sends an even to Sentry with warning severity. */
     readonly warning: (info: Parameters<typeof sendLogToSentry>[0], eventOptions?: EventContextAndTags) => string | undefined;
 };
-declare function sendLogToSentry(logInfo: SendLogInfo, eventDetails: EventDetails, options: ContextOptions): string | undefined;
+/**
+ * Runs the throttle decision and, if a state transition just occurred (`'started'` or `'ended'`)
+ * and `disableThrottleLog` is not set, emits the corresponding `Throttling started: ...` /
+ * `Throttling ended after suppressing N events: ...` warning via `sendLog.warning`. Returns whether
+ * the event should be throttled (i.e. dropped).
+ *
+ * @category Internal
+ */
+export declare function throttleEventWithLogging(event: Pick<TransactionEvent | ErrorEvent, 'message'>, 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
+ * have been registered yet, so events sent before Sentry init aren't accidentally throttled.
+ *
+ * @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 {};

package/dist/logging/send-log.js

@@ -4,6 +4,7 @@ import { convertEventDetailsToSentryContext, } from '../event-context/event-cont
 import { EventSeverityEnum } from '../event-context/event-severity.js';
 import { extractOriginalMessage } from '../processing/event-processor.js';
 import { LoggingState, logToConsoleWithoutSentry } from '../processing/log-to-console.js';
+import { combineThrottleThreshold, defaultThrottleOptions, getActiveThrottleOptions, shouldThrottleEvent, skipBeforeSendThrottleContextKey, } from '../processing/throttling.js';
 import { addPrematureEvent } from './premature-events.js';
 import { sentryClientForLogging } from './sentry-client-for-logging.js';
 /** Send non-error events to Sentry. */
@@ -15,6 +16,56 @@ export const sendLog = {
     /** Sends an even to Sentry with warning severity. */
     [EventSeverityEnum.Warning]: wrapLogWithSeverity(EventSeverityEnum.Warning),
 };
+/**
+ * Runs the throttle decision and, if a state transition just occurred (`'started'` or `'ended'`)
+ * and `disableThrottleLog` is not set, emits the corresponding `Throttling started: ...` /
+ * `Throttling ended after suppressing N events: ...` warning via `sendLog.warning`. Returns whether
+ * the event should be throttled (i.e. dropped).
+ *
+ * @category Internal
+ */
+export function throttleEventWithLogging(event, hint, options) {
+    const result = shouldThrottleEvent(event, hint, options);
+    const disableLog = options.disableThrottleLog ?? defaultThrottleOptions.disableThrottleLog;
+    if (!disableLog && result.errorKey != undefined) {
+        if (result.transition.kind === 'started') {
+            sendLog.warning(`Throttling started: ${result.errorKey}`, {
+                context: {
+                    suppressedErrorKey: result.errorKey,
+                },
+                tags: {
+                    suppressedErrorKey: result.errorKey,
+                },
+            });
+        }
+        else if (result.transition.kind === 'ended') {
+            sendLog.warning(`Throttling ended after suppressing ${result.transition.suppressedCount} events: ${result.errorKey}`, {
+                context: {
+                    suppressedErrorKey: result.errorKey,
+                    suppressedCount: result.transition.suppressedCount,
+                },
+                tags: {
+                    suppressedErrorKey: result.errorKey,
+                },
+            });
+        }
+    }
+    return result.shouldThrottle;
+}
+/**
+ * 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
+ * have been registered yet, so events sent before Sentry init aren't accidentally throttled.
+ *
+ * @category Internal
+ */
+export function checkActiveThrottle(event, hint, perCallThreshold) {
+    const active = getActiveThrottleOptions();
+    if (!active) {
+        return false;
+    }
+    return throttleEventWithLogging(event, hint, combineThrottleThreshold(active, perCallThreshold));
+}
 function wrapLogWithSeverity(severity) {
     return (info, eventOptions) => {
         return sendLogToSentry(info, {
@@ -24,10 +75,10 @@ function wrapLogWithSeverity(severity) {
             severity,
         }, {
             wasSentPrematurely: false,
-        });
+        }, eventOptions?.throttleThreshold);
     };
 }
-function sendLogToSentry(logInfo, eventDetails, options) {
+function sendLogToSentry(logInfo, eventDetails, options, perCallThrottleThreshold) {
     try {
         /**
          * `Error.message` is not enumerable, so spreading an `Error` into `captureEvent` would lose
@@ -51,9 +102,18 @@ function sendLogToSentry(logInfo, eventDetails, options) {
                 {
                     wasSentPrematurely: true,
                 },
+                perCallThrottleThreshold,
             ]);
             return undefined;
         }
+        const throttleMessage = check.isString(resolvedLogInfo)
+            ? resolvedLogInfo
+            : extractOriginalMessage(resolvedLogInfo, undefined);
+        if (checkActiveThrottle({
+            message: throttleMessage,
+        }, undefined, perCallThrottleThreshold)) {
+            return undefined;
+        }
         const scopeContext = convertEventDetailsToSentryContext(eventDetails, options);
         const client = sentryClientForLogging;
         function captureWithClient() {
@@ -64,14 +124,15 @@ function sendLogToSentry(logInfo, eventDetails, options) {
                     ...scopeContext,
                 });
         }
-        const eventId = eventDetails.attachments?.length
-            ? client.withScope((scope) => {
-                eventDetails.attachments?.forEach((attachment) => {
-                    scope.addAttachment(attachment);
-                });
-                return captureWithClient();
-            })
-            : captureWithClient();
+        const eventId = client.withScope((scope) => {
+            scope.setContext(skipBeforeSendThrottleContextKey, {
+                skipThrottle: true,
+            });
+            eventDetails.attachments?.forEach((attachment) => {
+                scope.addAttachment(attachment);
+            });
+            return captureWithClient();
+        });
         return eventId;
     }
     catch (caught) {

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

@@ -1,5 +1,7 @@
+import { extractExtraEventThrottleThreshold } from '../event-context/extra-event-context.js';
+import { throttleEventWithLogging } from '../logging/send-log.js';
 import { LoggingState, logToConsoleFromSentry } from './log-to-console.js';
-import { shouldThrottleEvent } from './throttling.js';
+import { combineThrottleThreshold, skipBeforeSendThrottleContextKey, } from './throttling.js';
 /** Creates a handler for Sentry events based on the given env. */
 export function createSentryHandler({ isDev, isSilent, throttleOptions, }) {
     /** The actual function that gets called when handling Sentry events. */
@@ -8,8 +10,15 @@ export function createSentryHandler({ isDev, isSilent, throttleOptions, }) {
     event, 
     /** The EventHint generated by Sentry. */
     hint) {
-        if (shouldThrottleEvent(event, hint, throttleOptions)) {
-            return null;
+        const wasPreThrottled = event.contexts?.[skipBeforeSendThrottleContextKey]?.skipThrottle === true;
+        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;
+            }
         }
         if (!event.extra?.wasSentPrematurely) {
             logToConsoleFromSentry(event, hint, isDev ? LoggingState.Dev : LoggingState.Prod, isSilent);

package/dist/processing/throttling.d.ts

@@ -49,7 +49,36 @@ export type ThrottleOptions = {
  */
 export declare const defaultThrottleOptions: ThrottleOptions;
 /**
- * Determines if an event should be throttled based on previous event counts.
+ * The state transition (if any) that just occurred for an error key. Used by callers to decide
+ * whether to emit a `"Throttling started"` or `"Throttling ended after suppressing N events"` log.
+ *
+ * @category Internal
+ */
+export type ThrottleTransition = {
+    kind: 'none';
+} | {
+    kind: 'started';
+} | {
+    kind: 'ended';
+    suppressedCount: number;
+};
+/**
+ * Result of a single {@link shouldThrottleEvent} call: whether the event should be dropped, the
+ * fuzzy cluster key it was bucketed into, and the state transition (if any) that the caller may
+ * want to surface as a log.
+ *
+ * @category Internal
+ */
+export type ThrottleResult = {
+    shouldThrottle: boolean;
+    /** Undefined when throttling is disabled (the event isn't bucketed). */
+    errorKey: FuzzyIndexKey | undefined;
+    transition: ThrottleTransition;
+};
+/**
+ * Determines whether an event should be throttled based on previous event counts.This does not emit
+ * any logs itself, the caller is expected to interpret `result.transition` and emit logs as
+ * appropriate.
  *
  * @category Internal
  */
@@ -57,4 +86,34 @@ export declare function shouldThrottleEvent(
 /** Event from Sentry. */
 event: Pick<TransactionEvent | ErrorEvent, 'message'>, 
 /** EventHint generated by Sentry. */
-hint?: Readonly<Pick<EventHint, 'originalException'>> | undefined, userOptions?: Readonly<PartialWithUndefined<ThrottleOptions>>): boolean;
+hint?: Readonly<Pick<EventHint, 'originalException'>> | undefined, userOptions?: Readonly<PartialWithUndefined<ThrottleOptions>>): ThrottleResult;
+/**
+ * Reserved key under `event.contexts` that `sendLog` and `handleError` set via `withScope` to tell
+ * `handleSentrySend` to skip its own throttle check — they've already done the check synchronously
+ * and the event passing through is one they chose to forward. Stripped from the event in
+ * `handleSentrySend` so it never reaches Sentry.
+ *
+ * @category Internal
+ */
+export declare const skipBeforeSendThrottleContextKey = "__sentryVirSkipThrottle";
+/**
+ * Sets the throttle options consulted by `shouldThrottleSync` (in `send-log.ts`). Called by
+ * `baseInitSentry`.
+ *
+ * @category Internal
+ */
+export declare function setActiveThrottleOptions(options: Readonly<PartialWithUndefined<ThrottleOptions>> | undefined): void;
+/**
+ * Returns the throttle options registered by the most recent `baseInitSentry` call, or `undefined`
+ * if Sentry has not yet been initialized.
+ *
+ * @category Internal
+ */
+export declare function getActiveThrottleOptions(): Readonly<PartialWithUndefined<ThrottleOptions>> | undefined;
+/**
+ * Combines a per-call throttle threshold with the active global throttle options, taking the
+ * minimum of the two so the per-call threshold can only ever tighten throttling.
+ *
+ * @category Internal
+ */
+export declare function combineThrottleThreshold(base: Readonly<PartialWithUndefined<ThrottleOptions>> | undefined, perCallThreshold: number | undefined): Readonly<PartialWithUndefined<ThrottleOptions>>;

package/dist/processing/throttling.js

@@ -1,7 +1,6 @@
 import { getOrSetFromMap, mergeDefinedProperties, } from '@augment-vir/common';
 import { calculateRelativeDate, getNowInUtcTimezone, isDateAfter, } from 'date-vir';
 import { FuzzyIndex } from 'fuzzy-vir';
-import { sendLog } from '../logging/send-log.js';
 import { extractOriginalMessage } from './event-processor.js';
 /**
  * The current throttle cache, keyed by a fuzzy cluster key so near-duplicate error messages share a
@@ -35,7 +34,9 @@ export const defaultThrottleOptions = {
     throttleThreshold: 500,
 };
 /**
- * Determines if an event should be throttled based on previous event counts.
+ * Determines whether an event should be throttled based on previous event counts.This does not emit
+ * any logs itself, the caller is expected to interpret `result.transition` and emit logs as
+ * appropriate.
  *
  * @category Internal
  */
@@ -46,7 +47,13 @@ event,
 hint, userOptions = defaultThrottleOptions) {
     const options = mergeDefinedProperties(defaultThrottleOptions, userOptions);
     if (options.disableThrottling) {
-        return false;
+        return {
+            shouldThrottle: false,
+            errorKey: undefined,
+            transition: {
+                kind: 'none',
+            },
+        };
     }
     const errorKey = fuzzyErrorIndex.insert(extractOriginalMessage(event, hint));
     const now = getNowInUtcTimezone();
@@ -56,21 +63,17 @@ hint, userOptions = defaultThrottleOptions) {
             intervalStartAt: now,
         };
     });
+    const transitionCandidates = [];
     const intervalNeedsRestart = isDateAfter({
         fullDate: now,
         relativeTo: calculateRelativeDate(errorThrottleData.intervalStartAt, options.thresholdInterval),
     });
     if (intervalNeedsRestart) {
         const suppressedCount = errorThrottleData.intervalCount - options.throttleThreshold;
-        if (suppressedCount > 0 && !options.disableThrottleLog) {
-            sendLog.warning(`Throttling ended after suppressing ${suppressedCount} events: ${errorKey}`, {
-                context: {
-                    suppressedErrorKey: errorKey,
-                    suppressedCount,
-                },
-                tags: {
-                    suppressedErrorKey: errorKey,
-                },
+        if (suppressedCount > 0) {
+            transitionCandidates.push({
+                kind: 'ended',
+                suppressedCount,
             });
         }
         errorThrottleData.intervalStartAt = now;
@@ -78,17 +81,67 @@ hint, userOptions = defaultThrottleOptions) {
     }
     errorThrottleData.intervalCount++;
     const shouldThrottle = errorThrottleData.intervalCount > options.throttleThreshold;
-    if (shouldThrottle &&
-        errorThrottleData.intervalCount === options.throttleThreshold + 1 &&
-        !options.disableThrottleLog) {
-        sendLog.warning(`Throttling started: ${errorKey}`, {
-            context: {
-                suppressedErrorKey: errorKey,
-            },
-            tags: {
-                suppressedErrorKey: errorKey,
-            },
+    if (shouldThrottle && errorThrottleData.intervalCount === options.throttleThreshold + 1) {
+        transitionCandidates.push({
+            kind: 'started',
         });
     }
-    return shouldThrottle;
+    return {
+        shouldThrottle,
+        errorKey,
+        transition: transitionCandidates[0] ?? {
+            kind: 'none',
+        },
+    };
+}
+/**
+ * Reserved key under `event.contexts` that `sendLog` and `handleError` set via `withScope` to tell
+ * `handleSentrySend` to skip its own throttle check — they've already done the check synchronously
+ * and the event passing through is one they chose to forward. Stripped from the event in
+ * `handleSentrySend` so it never reaches Sentry.
+ *
+ * @category Internal
+ */
+export const skipBeforeSendThrottleContextKey = '__sentryVirSkipThrottle';
+/**
+ * The throttle options currently in effect, set by {@link setActiveThrottleOptions} during Sentry
+ * initialization. Used by `sendLog` and `handleError` for their synchronous pre-capture throttle
+ * checks. `undefined` means Sentry has not yet been initialized.
+ *
+ * @category Internal
+ */
+let activeThrottleOptions;
+/**
+ * Sets the throttle options consulted by `shouldThrottleSync` (in `send-log.ts`). Called by
+ * `baseInitSentry`.
+ *
+ * @category Internal
+ */
+export function setActiveThrottleOptions(options) {
+    activeThrottleOptions = options;
+}
+/**
+ * Returns the throttle options registered by the most recent `baseInitSentry` call, or `undefined`
+ * if Sentry has not yet been initialized.
+ *
+ * @category Internal
+ */
+export function getActiveThrottleOptions() {
+    return activeThrottleOptions;
+}
+/**
+ * Combines a per-call throttle threshold with the active global throttle options, taking the
+ * minimum of the two so the per-call threshold can only ever tighten throttling.
+ *
+ * @category Internal
+ */
+export function combineThrottleThreshold(base, perCallThreshold) {
+    if (perCallThreshold == undefined) {
+        return base ?? {};
+    }
+    const baseThreshold = base?.throttleThreshold ?? defaultThrottleOptions.throttleThreshold;
+    return {
+        ...base,
+        throttleThreshold: Math.min(baseThreshold, perCallThreshold),
+    };
 }

package/package.json

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