@crawlee/core 4.0.0-beta.13 → 4.0.0-beta.131

package/autoscaling/snapshotter.d.ts

@@ -1,189 +1,84 @@
-import type { StorageClient } from '@crawlee/types';
-import type { Log } from '@apify/log';
-import type { BetterIntervalID } from '@apify/utilities';
-import { Configuration } from '../configuration.js';
-import type { EventManager } from '../events/event_manager.js';
-import type { SystemInfo } from './system_status.js';
-export interface SnapshotterOptions {
-    /**
-     * Defines the interval of measuring the event loop response time.
-     * @default 0.5
-     */
-    eventLoopSnapshotIntervalSecs?: number;
+import type { CpuLoadSignalOptions } from './cpu_load_signal.js';
+import type { EventLoopLoadSignalOptions } from './event_loop_load_signal.js';
+import type { LoadSignal, LoadSignalStartContext } from './load_signal.js';
+import type { MemoryLoadSignalOptions } from './memory_load_signal.js';
+import type { StorageBackendLoadSignalOptions } from './storage_backend_load_signal.js';
+/**
+ * The load signals a {@link ConcurrencySystem} watches to decide whether the machine is overloaded.
+ *
+ * Each of the four built-in signals is configured by passing its options bag — shorthand for constructing the
+ * corresponding {@link LoadSignal} class yourself, so `{ cpu: { overloadedRatio: 0.5 } }` is exactly
+ * `{ cpu: false, custom: [new CpuLoadSignal({ overloadedRatio: 0.5 })] }`. Pass `false` to leave a resource
+ * unwatched, and put anything else you want taken into account in {@link LoadSignalsOptions.custom|`custom`}.
+ *
+ * How far back the signals are evaluated is *not* set here, but by
+ * {@link ConcurrencySystemOptions.snapshotHistorySecs|`snapshotHistorySecs`} and
+ * {@link ConcurrencySystemOptions.currentHistorySecs|`currentHistorySecs`}.
+ */
+export interface LoadSignalsOptions {
     /**
-     * Defines the interval of checking the current state
-     * of the remote API client.
-     * @default 1
+     * Tuning for the built-in {@link MemoryLoadSignal} (used-memory limit + overload ratio), or `false` to switch
+     * it off.
      */
-    clientSnapshotIntervalSecs?: number;
+    memory?: MemoryLoadSignalOptions | false;
     /**
-     * Maximum allowed delay of the event loop in milliseconds.
-     * Exceeding this limit overloads the event loop.
-     * @default 50
+     * Tuning for the built-in {@link EventLoopLoadSignal} (snapshot interval + blocked-millis limit + overload
+     * ratio), or `false` to switch it off — which also stops its measuring interval.
      */
-    maxBlockedMillis?: number;
+    eventLoop?: EventLoopLoadSignalOptions | false;
     /**
-     * Defines the maximum ratio of total memory that can be used.
-     * Exceeding this limit overloads the memory.
-     * @default 0.9
+     * Tuning for the built-in {@link CpuLoadSignal} (overload ratio), or `false` to switch it off.
      */
-    maxUsedMemoryRatio?: number;
+    cpu?: CpuLoadSignalOptions | false;
     /**
-     * Defines the maximum number of new rate limit errors within
-     * the given interval.
-     * @default 1
+     * Tuning for the built-in {@link StorageBackendLoadSignal} (snapshot interval + error limit + overload ratio),
+     * or `false` to switch it off — worth doing when the storage backend reports no rate-limit statistics, since the
+     * signal otherwise polls it every second to no purpose.
      */
-    maxClientErrors?: number;
+    storageBackend?: StorageBackendLoadSignalOptions | false;
     /**
-     * Sets the interval in seconds for which a history of resource snapshots
-     * will be kept. Increasing this to very high numbers will affect performance.
-     * @default 60
+     * Additional {@link LoadSignal} implementations — e.g. navigation timeouts or proxy health — evaluated
+     * alongside the built-in four. If any signal reports overload, the system counts as overloaded. Their lifecycle
+     * is driven by the {@link ConcurrencySystem} they are given to, and their {@link LoadSignal.name|names} must
+     * not collide with an enabled built-in's.
      */
-    snapshotHistorySecs?: number;
-    /** @internal */
-    log?: Log;
-    /** @internal */
-    client?: StorageClient;
-    /** @internal */
-    config?: Configuration;
-}
-interface MemorySnapshot {
-    createdAt: Date;
-    isOverloaded: boolean;
-    usedBytes?: number;
-}
-interface CpuSnapshot {
-    createdAt: Date;
-    isOverloaded: boolean;
-    usedRatio: number;
-    ticks?: {
-        idle: number;
-        total: number;
-    };
-}
-interface EventLoopSnapshot {
-    createdAt: Date;
-    isOverloaded: boolean;
-    exceededMillis: number;
-}
-interface ClientSnapshot {
-    createdAt: Date;
-    isOverloaded: boolean;
-    rateLimitErrorCount: number;
+    custom?: LoadSignal[];
 }
 /**
- * Creates snapshots of system resources at given intervals and marks the resource
- * as either overloaded or not during the last interval. Keeps a history of the snapshots.
- * It tracks the following resources: Memory, EventLoop, API and CPU.
- * The class is used by the {@link AutoscaledPool} class.
- *
- * When running on the Apify platform, the CPU and memory statistics are provided by the platform,
- * as collected from the running Docker container. When running locally, `Snapshotter`
- * makes its own statistics by querying the OS.
- *
- * CPU becomes overloaded locally when its current use exceeds the `maxUsedCpuRatio` option or
- * when Apify platform marks it as overloaded.
- *
- * Memory becomes overloaded if its current use exceeds the `maxUsedMemoryRatio` option.
- * It's computed using the total memory available to the container when running on
- * the Apify platform and a quarter of total system memory when running locally.
- * Max total memory when running locally may be overridden by using the `CRAWLEE_MEMORY_MBYTES`
- * environment variable.
- *
- * Event loop becomes overloaded if it slows down by more than the `maxBlockedMillis` option.
+ * An implementation detail of the {@link ConcurrencySystem}: the built-in signal tuning from
+ * {@link LoadSignalsOptions}, minus the custom signals, which the system evaluates itself rather than collecting
+ * them here.
+ * @internal
+ */
+export type SnapshotterOptions = Omit<LoadSignalsOptions, 'custom'>;
+/**
+ * Owns the four built-in {@link LoadSignal} instances — {@link MemoryLoadSignal},
+ * {@link EventLoopLoadSignal}, {@link CpuLoadSignal} and {@link StorageBackendLoadSignal} — constructing
+ * the ones that were not switched off and driving their shared lifecycle.
  *
- * Client becomes overloaded when rate limit errors (429 - Too Many Requests),
- * typically received from the request queue, exceed the set limit within the set interval.
- * @category Scaling
+ * Configured indirectly through {@link ConcurrencySystemOptions.loadSignals|`loadSignals`}, whose per-signal bags
+ * are simply forwarded to the corresponding constructor.
+ * @internal
  */
 export declare class Snapshotter {
-    log: Log;
-    client: StorageClient;
-    config: Configuration;
-    events: EventManager;
-    eventLoopSnapshotIntervalMillis: number;
-    clientSnapshotIntervalMillis: number;
-    snapshotHistoryMillis: number;
-    maxBlockedMillis: number;
-    maxUsedMemoryRatio: number;
-    maxClientErrors: number;
-    maxMemoryBytes: number;
-    cpuSnapshots: CpuSnapshot[];
-    eventLoopSnapshots: EventLoopSnapshot[];
-    memorySnapshots: MemorySnapshot[];
-    clientSnapshots: ClientSnapshot[];
-    eventLoopInterval: BetterIntervalID;
-    clientInterval: BetterIntervalID;
-    lastLoggedCriticalMemoryOverloadAt: Date | null;
+    #private;
+    /**
+     * Returns the enabled built-in signals, so `SystemStatus` can iterate them alongside any custom `LoadSignal`
+     * instances. Signals switched off through the options are simply absent — the system status reports them as
+     * not overloaded.
+     */
+    getLoadSignals(): LoadSignal[];
     /**
      * @param [options] All `Snapshotter` configuration options.
      */
     constructor(options?: SnapshotterOptions);
     /**
-     * Starts capturing snapshots at configured intervals.
+     * Starts capturing snapshots at configured intervals. The `context` carries the sample window the signals will
+     * be queried with, which is also how much history they retain.
      */
-    start(): Promise<void>;
+    start(context: LoadSignalStartContext): Promise<void>;
     /**
      * Stops all resource capturing.
      */
     stop(): Promise<void>;
-    /**
-     * Returns a sample of latest memory snapshots, with the size of the sample defined
-     * by the sampleDurationMillis parameter. If omitted, it returns a full snapshot history.
-     */
-    getMemorySample(sampleDurationMillis?: number): MemorySnapshot[];
-    /**
-     * Returns a sample of latest event loop snapshots, with the size of the sample defined
-     * by the sampleDurationMillis parameter. If omitted, it returns a full snapshot history.
-     */
-    getEventLoopSample(sampleDurationMillis?: number): EventLoopSnapshot[];
-    /**
-     * Returns a sample of latest CPU snapshots, with the size of the sample defined
-     * by the sampleDurationMillis parameter. If omitted, it returns a full snapshot history.
-     */
-    getCpuSample(sampleDurationMillis?: number): CpuSnapshot[];
-    /**
-     * Returns a sample of latest Client snapshots, with the size of the sample defined
-     * by the sampleDurationMillis parameter. If omitted, it returns a full snapshot history.
-     */
-    getClientSample(sampleDurationMillis?: number): ClientSnapshot[];
-    /**
-     * Finds the latest snapshots by sampleDurationMillis in the provided array.
-     */
-    protected _getSample<T extends {
-        createdAt: Date;
-    }>(snapshots: T[], sampleDurationMillis?: number): T[];
-    /**
-     * Creates a snapshot of current memory usage
-     * using the Apify platform `systemInfo` event.
-     */
-    protected _snapshotMemory(systemInfo: SystemInfo): void;
-    /**
-     * Checks for critical memory overload and logs it to the console.
-     */
-    protected _memoryOverloadWarning(systemInfo: SystemInfo): void;
-    /**
-     * Creates a snapshot of current event loop delay.
-     */
-    protected _snapshotEventLoop(intervalCallback: () => unknown): void;
-    /**
-     * Creates a snapshot of current CPU usage using the Apify platform `systemInfo` event.
-     */
-    protected _snapshotCpu(systemInfo: SystemInfo): void;
-    /**
-     * Creates a snapshot of current API state by checking for
-     * rate limit errors. Only errors produced by a 2nd retry
-     * of the API call are considered for snapshotting since
-     * earlier errors may just be caused by a random spike in
-     * number of requests and do not necessarily signify API
-     * overloading.
-     */
-    protected _snapshotClient(intervalCallback: () => unknown): void;
-    /**
-     * Removes snapshots that are older than the snapshotHistorySecs option
-     * from the array (destructively - in place).
-     */
-    protected _pruneSnapshots(snapshots: MemorySnapshot[] | CpuSnapshot[] | EventLoopSnapshot[] | ClientSnapshot[], now: Date): void;
 }
-export {};
-//# sourceMappingURL=snapshotter.d.ts.map

package/autoscaling/snapshotter.js

@@ -1,285 +1,67 @@
-import { getMemoryInfo, isContainerized } from '@crawlee/utils';
-import ow from 'ow';
-import { betterClearInterval, betterSetInterval } from '@apify/utilities';
-import { Configuration } from '../configuration.js';
-import { log as defaultLog } from '../log.js';
-const RESERVE_MEMORY_RATIO = 0.5;
-const CLIENT_RATE_LIMIT_ERROR_RETRY_COUNT = 2;
-const CRITICAL_OVERLOAD_RATE_LIMIT_MILLIS = 10000;
+import { CpuLoadSignal } from './cpu_load_signal.js';
+import { EventLoopLoadSignal } from './event_loop_load_signal.js';
+import { MemoryLoadSignal } from './memory_load_signal.js';
+import { StorageBackendLoadSignal } from './storage_backend_load_signal.js';
 /**
- * Creates snapshots of system resources at given intervals and marks the resource
- * as either overloaded or not during the last interval. Keeps a history of the snapshots.
- * It tracks the following resources: Memory, EventLoop, API and CPU.
- * The class is used by the {@link AutoscaledPool} class.
+ * Owns the four built-in {@link LoadSignal} instances — {@link MemoryLoadSignal},
+ * {@link EventLoopLoadSignal}, {@link CpuLoadSignal} and {@link StorageBackendLoadSignal} — constructing
+ * the ones that were not switched off and driving their shared lifecycle.
  *
- * When running on the Apify platform, the CPU and memory statistics are provided by the platform,
- * as collected from the running Docker container. When running locally, `Snapshotter`
- * makes its own statistics by querying the OS.
- *
- * CPU becomes overloaded locally when its current use exceeds the `maxUsedCpuRatio` option or
- * when Apify platform marks it as overloaded.
- *
- * Memory becomes overloaded if its current use exceeds the `maxUsedMemoryRatio` option.
- * It's computed using the total memory available to the container when running on
- * the Apify platform and a quarter of total system memory when running locally.
- * Max total memory when running locally may be overridden by using the `CRAWLEE_MEMORY_MBYTES`
- * environment variable.
- *
- * Event loop becomes overloaded if it slows down by more than the `maxBlockedMillis` option.
- *
- * Client becomes overloaded when rate limit errors (429 - Too Many Requests),
- * typically received from the request queue, exceed the set limit within the set interval.
- * @category Scaling
+ * Configured indirectly through {@link ConcurrencySystemOptions.loadSignals|`loadSignals`}, whose per-signal bags
+ * are simply forwarded to the corresponding constructor.
+ * @internal
  */
 export class Snapshotter {
-    log;
-    client;
-    config;
-    events;
-    eventLoopSnapshotIntervalMillis;
-    clientSnapshotIntervalMillis;
-    snapshotHistoryMillis;
-    maxBlockedMillis;
-    maxUsedMemoryRatio;
-    maxClientErrors;
-    maxMemoryBytes;
-    cpuSnapshots = [];
-    eventLoopSnapshots = [];
-    memorySnapshots = [];
-    clientSnapshots = [];
-    eventLoopInterval = null;
-    clientInterval = null;
-    lastLoggedCriticalMemoryOverloadAt = null;
+    // Absent when switched off through the corresponding option (e.g. `storageBackend: false`).
+    #memorySignal;
+    #eventLoopSignal;
+    #cpuSignal;
+    #storageBackendSignal;
+    /**
+     * Returns the enabled built-in signals, so `SystemStatus` can iterate them alongside any custom `LoadSignal`
+     * instances. Signals switched off through the options are simply absent — the system status reports them as
+     * not overloaded.
+     */
+    getLoadSignals() {
+        const builtin = [
+            this.#memorySignal,
+            this.#eventLoopSignal,
+            this.#cpuSignal,
+            this.#storageBackendSignal,
+        ];
+        return builtin.filter((signal) => signal !== undefined);
+    }
     /**
      * @param [options] All `Snapshotter` configuration options.
      */
     constructor(options = {}) {
-        ow(options, ow.object.exactShape({
-            eventLoopSnapshotIntervalSecs: ow.optional.number,
-            clientSnapshotIntervalSecs: ow.optional.number,
-            snapshotHistorySecs: ow.optional.number,
-            maxBlockedMillis: ow.optional.number,
-            maxUsedMemoryRatio: ow.optional.number,
-            maxClientErrors: ow.optional.number,
-            log: ow.optional.object,
-            client: ow.optional.object,
-            config: ow.optional.object,
-        }));
-        const { eventLoopSnapshotIntervalSecs = 0.5, clientSnapshotIntervalSecs = 1, snapshotHistorySecs = 30, maxBlockedMillis = 50, maxUsedMemoryRatio = 0.9, maxClientErrors = 3, log = defaultLog, config = Configuration.getGlobalConfig(), client = config.getStorageClient(), } = options;
-        this.log = log.child({ prefix: 'Snapshotter' });
-        this.client = client;
-        this.config = config;
-        this.events = this.config.getEventManager();
-        this.eventLoopSnapshotIntervalMillis = eventLoopSnapshotIntervalSecs * 1000;
-        this.clientSnapshotIntervalMillis = clientSnapshotIntervalSecs * 1000;
-        this.snapshotHistoryMillis = snapshotHistorySecs * 1000;
-        this.maxBlockedMillis = maxBlockedMillis;
-        this.maxUsedMemoryRatio = maxUsedMemoryRatio;
-        this.maxClientErrors = maxClientErrors;
-        // We need to pre-bind those functions to be able to successfully remove listeners.
-        this._snapshotCpu = this._snapshotCpu.bind(this);
-        this._snapshotMemory = this._snapshotMemory.bind(this);
+        const { memory = {}, eventLoop = {}, cpu = {}, storageBackend = {} } = options;
+        // Each signal resolves its own ambient dependencies when started, and is told the window it will be sampled
+        // over then too - so there is nothing to thread in here beyond the caller's tuning.
+        if (memory !== false)
+            this.#memorySignal = new MemoryLoadSignal(memory);
+        if (eventLoop !== false)
+            this.#eventLoopSignal = new EventLoopLoadSignal(eventLoop);
+        if (cpu !== false)
+            this.#cpuSignal = new CpuLoadSignal(cpu);
+        if (storageBackend !== false)
+            this.#storageBackendSignal = new StorageBackendLoadSignal(storageBackend);
     }
     /**
-     * Starts capturing snapshots at configured intervals.
+     * Starts capturing snapshots at configured intervals. The `context` carries the sample window the signals will
+     * be queried with, which is also how much history they retain.
      */
-    async start() {
-        const memoryMbytes = this.config.get('memoryMbytes', 0);
-        if (memoryMbytes > 0) {
-            this.maxMemoryBytes = memoryMbytes * 1024 * 1024;
-        }
-        else {
-            const containerized = this.config.get('containerized', await isContainerized());
-            const memInfo = await getMemoryInfo(containerized);
-            const totalBytes = memInfo.totalBytes;
-            this.maxMemoryBytes = Math.ceil(totalBytes * this.config.get('availableMemoryRatio'));
-            this.log.debug(`Setting max memory of this run to ${Math.round(this.maxMemoryBytes / 1024 / 1024)} MB. ` +
-                'Use the CRAWLEE_MEMORY_MBYTES or CRAWLEE_AVAILABLE_MEMORY_RATIO environment variable to override it.');
-        }
-        // Start snapshotting.
-        this.eventLoopInterval = betterSetInterval(this._snapshotEventLoop.bind(this), this.eventLoopSnapshotIntervalMillis);
-        this.clientInterval = betterSetInterval(this._snapshotClient.bind(this), this.clientSnapshotIntervalMillis);
-        this.events.on("systemInfo" /* EventType.SYSTEM_INFO */, this._snapshotCpu);
-        this.events.on("systemInfo" /* EventType.SYSTEM_INFO */, this._snapshotMemory);
+    async start(context) {
+        await Promise.all(this.getLoadSignals().map(async (signal) => signal.start(context)));
     }
     /**
      * Stops all resource capturing.
      */
     async stop() {
-        betterClearInterval(this.eventLoopInterval);
-        betterClearInterval(this.clientInterval);
-        this.events.off("systemInfo" /* EventType.SYSTEM_INFO */, this._snapshotCpu);
-        this.events.off("systemInfo" /* EventType.SYSTEM_INFO */, this._snapshotMemory);
+        await Promise.all(this.getLoadSignals().map(async (signal) => signal.stop()));
         // Allow microtask queue to unwind before stop returns.
         await new Promise((resolve) => {
             setImmediate(resolve);
         });
     }
-    /**
-     * Returns a sample of latest memory snapshots, with the size of the sample defined
-     * by the sampleDurationMillis parameter. If omitted, it returns a full snapshot history.
-     */
-    getMemorySample(sampleDurationMillis) {
-        return this._getSample(this.memorySnapshots, sampleDurationMillis);
-    }
-    /**
-     * Returns a sample of latest event loop snapshots, with the size of the sample defined
-     * by the sampleDurationMillis parameter. If omitted, it returns a full snapshot history.
-     */
-    getEventLoopSample(sampleDurationMillis) {
-        return this._getSample(this.eventLoopSnapshots, sampleDurationMillis);
-    }
-    /**
-     * Returns a sample of latest CPU snapshots, with the size of the sample defined
-     * by the sampleDurationMillis parameter. If omitted, it returns a full snapshot history.
-     */
-    getCpuSample(sampleDurationMillis) {
-        return this._getSample(this.cpuSnapshots, sampleDurationMillis);
-    }
-    /**
-     * Returns a sample of latest Client snapshots, with the size of the sample defined
-     * by the sampleDurationMillis parameter. If omitted, it returns a full snapshot history.
-     */
-    getClientSample(sampleDurationMillis) {
-        return this._getSample(this.clientSnapshots, sampleDurationMillis);
-    }
-    /**
-     * Finds the latest snapshots by sampleDurationMillis in the provided array.
-     */
-    _getSample(snapshots, sampleDurationMillis) {
-        if (!sampleDurationMillis)
-            return snapshots;
-        const sample = [];
-        let idx = snapshots.length;
-        if (!idx)
-            return sample;
-        const latestTime = snapshots[idx - 1].createdAt;
-        while (idx--) {
-            const snapshot = snapshots[idx];
-            if (+latestTime - +snapshot.createdAt <= sampleDurationMillis) {
-                sample.unshift(snapshot);
-            }
-            else {
-                break;
-            }
-        }
-        return sample;
-    }
-    /**
-     * Creates a snapshot of current memory usage
-     * using the Apify platform `systemInfo` event.
-     */
-    _snapshotMemory(systemInfo) {
-        const createdAt = systemInfo.createdAt ? new Date(systemInfo.createdAt) : new Date();
-        this._pruneSnapshots(this.memorySnapshots, createdAt);
-        const { memCurrentBytes } = systemInfo;
-        const snapshot = {
-            createdAt,
-            isOverloaded: memCurrentBytes / this.maxMemoryBytes > this.maxUsedMemoryRatio,
-            usedBytes: memCurrentBytes,
-        };
-        this.memorySnapshots.push(snapshot);
-        this._memoryOverloadWarning(systemInfo);
-    }
-    /**
-     * Checks for critical memory overload and logs it to the console.
-     */
-    _memoryOverloadWarning(systemInfo) {
-        const { memCurrentBytes } = systemInfo;
-        const createdAt = systemInfo.createdAt ? new Date(systemInfo.createdAt) : new Date();
-        if (this.lastLoggedCriticalMemoryOverloadAt &&
-            +createdAt < +this.lastLoggedCriticalMemoryOverloadAt + CRITICAL_OVERLOAD_RATE_LIMIT_MILLIS)
-            return;
-        const maxDesiredMemoryBytes = this.maxUsedMemoryRatio * this.maxMemoryBytes;
-        const reserveMemory = this.maxMemoryBytes * (1 - this.maxUsedMemoryRatio) * RESERVE_MEMORY_RATIO;
-        const criticalOverloadBytes = maxDesiredMemoryBytes + reserveMemory;
-        const isCriticalOverload = memCurrentBytes > criticalOverloadBytes;
-        if (isCriticalOverload) {
-            const usedPercentage = Math.round((memCurrentBytes / this.maxMemoryBytes) * 100);
-            const toMb = (bytes) => Math.round(bytes / 1024 ** 2);
-            this.log.warning('Memory is critically overloaded. ' +
-                `Using ${toMb(memCurrentBytes)} MB of ${toMb(this.maxMemoryBytes)} MB (${usedPercentage}%). Consider increasing available memory.`);
-            this.lastLoggedCriticalMemoryOverloadAt = createdAt;
-        }
-    }
-    /**
-     * Creates a snapshot of current event loop delay.
-     */
-    _snapshotEventLoop(intervalCallback) {
-        const now = new Date();
-        this._pruneSnapshots(this.eventLoopSnapshots, now);
-        const snapshot = {
-            createdAt: now,
-            isOverloaded: false,
-            exceededMillis: 0,
-        };
-        const previousSnapshot = this.eventLoopSnapshots[this.eventLoopSnapshots.length - 1];
-        if (previousSnapshot) {
-            const { createdAt } = previousSnapshot;
-            const delta = now.getTime() - +createdAt - this.eventLoopSnapshotIntervalMillis;
-            if (delta > this.maxBlockedMillis)
-                snapshot.isOverloaded = true;
-            snapshot.exceededMillis = Math.max(delta - this.maxBlockedMillis, 0);
-        }
-        this.eventLoopSnapshots.push(snapshot);
-        intervalCallback();
-    }
-    /**
-     * Creates a snapshot of current CPU usage using the Apify platform `systemInfo` event.
-     */
-    _snapshotCpu(systemInfo) {
-        const { cpuCurrentUsage, isCpuOverloaded } = systemInfo;
-        const createdAt = systemInfo.createdAt ? new Date(systemInfo.createdAt) : new Date();
-        this._pruneSnapshots(this.cpuSnapshots, createdAt);
-        this.cpuSnapshots.push({
-            createdAt,
-            isOverloaded: isCpuOverloaded,
-            usedRatio: Math.ceil(cpuCurrentUsage / 100),
-        });
-    }
-    /**
-     * Creates a snapshot of current API state by checking for
-     * rate limit errors. Only errors produced by a 2nd retry
-     * of the API call are considered for snapshotting since
-     * earlier errors may just be caused by a random spike in
-     * number of requests and do not necessarily signify API
-     * overloading.
-     */
-    _snapshotClient(intervalCallback) {
-        const now = new Date();
-        this._pruneSnapshots(this.clientSnapshots, now);
-        const allErrorCounts = this.client.stats?.rateLimitErrors ?? []; // storage client might not support this
-        const currentErrCount = allErrorCounts[CLIENT_RATE_LIMIT_ERROR_RETRY_COUNT] || 0;
-        // Handle empty snapshots array
-        const snapshot = {
-            createdAt: now,
-            isOverloaded: false,
-            rateLimitErrorCount: currentErrCount,
-        };
-        const previousSnapshot = this.clientSnapshots[this.clientSnapshots.length - 1];
-        if (previousSnapshot) {
-            const { rateLimitErrorCount } = previousSnapshot;
-            const delta = currentErrCount - rateLimitErrorCount;
-            if (delta > this.maxClientErrors)
-                snapshot.isOverloaded = true;
-        }
-        this.clientSnapshots.push(snapshot);
-        intervalCallback();
-    }
-    /**
-     * Removes snapshots that are older than the snapshotHistorySecs option
-     * from the array (destructively - in place).
-     */
-    _pruneSnapshots(snapshots, now) {
-        let oldCount = 0;
-        for (let i = 0; i < snapshots.length; i++) {
-            const { createdAt } = snapshots[i];
-            if (now.getTime() - new Date(createdAt).getTime() > this.snapshotHistoryMillis)
-                oldCount++;
-            else
-                break;
-        }
-        snapshots.splice(0, oldCount);
-    }
 }
-//# sourceMappingURL=snapshotter.js.map

package/autoscaling/storage_backend_load_signal.d.ts

@@ -0,0 +1,56 @@
+import type { LoadSignal, LoadSignalStartContext, LoadSnapshot } from './load_signal.js';
+/**
+ * A snapshot produced by the built-in storage backend (rate-limit) signal.
+ * @internal
+ */
+export interface StorageBackendSnapshot extends LoadSnapshot {
+    rateLimitErrorCount: number;
+}
+/**
+ * Tuning for the built-in **storage backend** (rate-limit) load signal, as accepted both by
+ * {@link StorageBackendLoadSignal} and by the
+ * {@link LoadSignalsOptions.storageBackend|`storageBackend`} shorthand on {@link LoadSignalsOptions}.
+ */
+export interface StorageBackendLoadSignalOptions {
+    /**
+     * Defines the interval of checking the current state of the storage backend, in seconds.
+     * @default 1
+     */
+    snapshotIntervalSecs?: number;
+    /**
+     * Defines the maximum number of new rate limit errors within the given interval.
+     * @default 3
+     */
+    maxErrors?: number;
+    /**
+     * Maximum ratio of overloaded snapshots in a sample before the storage backend counts as overloaded.
+     * @default 0.3
+     */
+    overloadedRatio?: number;
+}
+/**
+ * Periodically checks the storage backend for rate-limit errors (HTTP 429) and reports overload when the error delta
+ * exceeds a threshold.
+ *
+ * Built by default; construct one yourself only to wrap or adapt it — see {@link LoadSignal}.
+ *
+ * Switch it off entirely ({@link LoadSignalsOptions.storageBackend|`storageBackend: false`}) if the storage backend
+ * reports no rate-limit statistics, since it otherwise polls it every second to no purpose.
+ *
+ * @category Scaling
+ */
+export declare class StorageBackendLoadSignal implements LoadSignal {
+    #private;
+    readonly name = "storageBackendInfo";
+    readonly overloadedRatio: number;
+    constructor(options?: StorageBackendLoadSignalOptions);
+    start(context: LoadSignalStartContext): Promise<void>;
+    stop(): Promise<void>;
+    getSample(sampleDurationMillis?: number): LoadSnapshot[];
+    /**
+     * Records one snapshot, overloaded when rate-limit errors grew by more than the configured limit since the
+     * previous one.
+     * @internal Also lets tests drive the measurement without waiting on a timer.
+     */
+    handle(intervalCallback: () => unknown): void;
+}