@zintrust/trace 0.5.2 → 0.5.4

package/README.md

@@ -2,6 +2,8 @@
 
 A debug assistant for ZinTrust. Records HTTP requests, database queries, exceptions, jobs, cache operations, scheduled tasks, mail, auth events, and more — all surfaced through a built-in web dashboard.
 
+Docs: https://zintrust.com/package-trace
+
 Works with both `zin s` (Node.js) and `zin s --wg` (Cloudflare Workers).
 
 ---
@@ -33,8 +35,25 @@ TRACE_QUERY_CONNECTION=main   # optional — app DB to observe for SQL traces
 TRACE_PRUNE_HOURS=24          # how long entries are kept (default: 24)
 TRACE_SLOW_QUERY_MS=100       # slow-query threshold in ms (default: 100)
 TRACE_LOG_LEVEL=info          # minimum log level captured (default: info)
+TRACE_CACHE_PAYLOADS=false    # optional — include cache payload values in trace entries
+TRACE_QUERY_BINDINGS=true     # optional — include SQL binding values in query traces
+TRACE_CONTENT_QUEUE_DRIVER=   # optional — any registered async queue driver for trace offload
+TRACE_CONTENT_QUEUE_NAME=trace-content
+TRACE_CONTENT_QUEUE_ENQUEUE_TIMEOUT_MS=25
+TRACE_CONTENT_QUEUE_WORKER_ENABLED=true
+TRACE_CONTENT_QUEUE_WORKER_INTERVAL_MS=1000
+TRACE_CONTENT_QUEUE_WORKER_MAX_DURATION_MS=250
+TRACE_CONTENT_QUEUE_WORKER_CONCURRENCY=1
+TRACE_REDACT_KEYS=password,token,secret
+TRACE_REDACT_HEADERS=authorization,cookie
+TRACE_REDACT_BODY=password,token,secret
+TRACE_REDACT_QUERY=
 ```
 
+When `TRACE_CONTENT_QUEUE_DRIVER` is set, trace writes enqueue through that registered queue driver and an internal trace worker drains them outside the live request path. When it is unset, oversized content is replaced with `Trace content exceeded budget and was replaced.` before persistence instead of running the heavy compaction loop inline.
+
+This currently works with any queue driver already registered in ZinTrust. First-class Cloudflare Queue support still requires a dedicated queue driver and queue-runtime registration for that transport.
+
 ### 2. Enable the plugin in `zintrust.plugins.*`
 
 The supported setup is to opt in through your ZinTrust plugin files, not a custom `src/start.ts` import.
@@ -82,6 +101,19 @@ export default {
   pruneAfterHours: Env.getInt('TRACE_PRUNE_HOURS', 24),
   slowQueryThreshold: Env.getInt('TRACE_SLOW_QUERY_MS', 100),
   logMinLevel: Env.get('TRACE_LOG_LEVEL', 'info') as TraceConfigOverrides['logMinLevel'],
+  captureCachePayloads: Env.getBool('TRACE_CACHE_PAYLOADS', false),
+  captureQueryBindings: Env.getBool('TRACE_QUERY_BINDINGS', true),
+  contentDispatch: {
+    driver: Env.get('TRACE_CONTENT_QUEUE_DRIVER', '') || undefined,
+    queueName: Env.get('TRACE_CONTENT_QUEUE_NAME', 'trace-content'),
+    enqueueTimeoutMs: Env.getInt('TRACE_CONTENT_QUEUE_ENQUEUE_TIMEOUT_MS', 25),
+    worker: {
+      enabled: Env.getBool('TRACE_CONTENT_QUEUE_WORKER_ENABLED', true),
+      intervalMs: Env.getInt('TRACE_CONTENT_QUEUE_WORKER_INTERVAL_MS', 1000),
+      maxDurationMs: Env.getInt('TRACE_CONTENT_QUEUE_WORKER_MAX_DURATION_MS', 250),
+      concurrency: Env.getInt('TRACE_CONTENT_QUEUE_WORKER_CONCURRENCY', 1),
+    },
+  },
   watchers: {
     request: {
       get: { exclude: ['report'] },
@@ -258,19 +290,29 @@ ExceptionWatcher.register({ storage, config, db });
 
 `TraceConfig.merge(overrides?)` accepts the following options:
 
-| Option               | Type                                                | Default                            | Description                                                                  |
-| -------------------- | --------------------------------------------------- | ---------------------------------- | ---------------------------------------------------------------------------- |
-| `enabled`            | `boolean`                                           | `false`                            | Master switch — no watchers activate when `false`                            |
-| `connection`         | `string \| undefined`                               | `undefined`                        | Named DB connection for storing entries; uses `'default'` if omitted         |
-| `pruneAfterHours`    | `number`                                            | `24`                               | Entries older than this are pruned                                           |
-| `slowQueryThreshold` | `number`                                            | `100`                              | Queries taking longer (ms) are flagged as slow                               |
-| `logMinLevel`        | `'debug' \| 'info' \| 'warn' \| 'error' \| 'fatal'` | `'info'`                           | Minimum log severity captured                                                |
-| `ignoreRoutes`       | `string[]`                                          | `['/trace', '/health', '/ping']`   | Routes excluded from HTTP watcher                                            |
-| `watchers`           | `Record<string, boolean \| { include?, exclude? }>` | `{}`                               | Per-watcher enable/disable flags plus contains-based include/exclude filters |
-| `redaction.keys`     | `string[]`                                          | common auth/card/session keys      | Extra sensitive keys redacted recursively before trace persistence           |
-| `redaction.headers`  | `string[]`                                          | `['authorization', 'cookie', ...]` | Request header names to redact                                               |
-| `redaction.body`     | `string[]`                                          | `['password', 'token', ...]`       | Request body keys to redact                                                  |
-| `redaction.query`    | `string[]`                                          | `[]`                               | Query-string keys to redact                                                  |
+| Option                                 | Type                                                | Default                            | Description                                                                    |
+| -------------------------------------- | --------------------------------------------------- | ---------------------------------- | ------------------------------------------------------------------------------ |
+| `enabled`                              | `boolean`                                           | `false`                            | Master switch — no watchers activate when `false`                              |
+| `connection`                           | `string \| undefined`                               | `undefined`                        | Named DB connection for storing entries; uses `'default'` if omitted           |
+| `observeConnection`                    | `string \| undefined`                               | `undefined`                        | Separate observed DB connection for query tracing when storage uses another DB |
+| `pruneAfterHours`                      | `number`                                            | `24`                               | Entries older than this are pruned                                             |
+| `slowQueryThreshold`                   | `number`                                            | `100`                              | Queries taking longer (ms) are flagged as slow                                 |
+| `logMinLevel`                          | `'debug' \| 'info' \| 'warn' \| 'error' \| 'fatal'` | `'info'`                           | Minimum log severity captured                                                  |
+| `captureCachePayloads`                 | `boolean`                                           | `false`                            | Include cache payload values in cache trace entries                            |
+| `captureQueryBindings`                 | `boolean`                                           | `true`                             | Include SQL binding values in query trace entries                              |
+| `contentDispatch.driver`               | `string \| undefined`                               | `undefined`                        | Registered queue driver used for async trace content offload                   |
+| `contentDispatch.queueName`            | `string`                                            | `'trace-content'`                  | Queue name used for offloaded trace content writes                             |
+| `contentDispatch.enqueueTimeoutMs`     | `number`                                            | `25`                               | Max enqueue wait before trace falls back to fail-open persistence              |
+| `contentDispatch.worker.enabled`       | `boolean`                                           | `true`                             | Enables the internal trace queue drain worker                                  |
+| `contentDispatch.worker.intervalMs`    | `number`                                            | `1000`                             | Poll interval for the internal trace queue drain worker                        |
+| `contentDispatch.worker.maxDurationMs` | `number`                                            | `250`                              | Max runtime per drain pass before the worker yields                            |
+| `contentDispatch.worker.concurrency`   | `number`                                            | `1`                                | Number of concurrent queue-drain loops for the internal trace worker           |
+| `ignoreRoutes`                         | `string[]`                                          | `['/trace', '/health', '/ping']`   | Routes excluded from HTTP watcher                                              |
+| `watchers`                             | `Record<string, boolean \| { include?, exclude? }>` | `{}`                               | Per-watcher enable/disable flags plus contains-based include/exclude filters   |
+| `redaction.keys`                       | `string[]`                                          | common auth/card/session keys      | Extra sensitive keys redacted recursively before trace persistence             |
+| `redaction.headers`                    | `string[]`                                          | `['authorization', 'cookie', ...]` | Request header names to redact                                                 |
+| `redaction.body`                       | `string[]`                                          | `['password', 'token', ...]`       | Request body keys to redact                                                    |
+| `redaction.query`                      | `string[]`                                          | `[]`                               | Query-string keys to redact                                                    |
 
 Request watcher filters can also be scoped per method. Matching is contains-based against the stored trace content, so values like `report`, `auth`, or `trace` match any request or entry whose content includes those fragments.
 

package/dist/config.js

@@ -150,6 +150,19 @@ const mergeWatchers = (base, override) => {
         clientRequest: mergeClientRequestWatcherToggle(base.clientRequest, override.clientRequest),
     };
 };
+const mergeContentDispatch = (base, override) => {
+    const workerOverride = override?.worker;
+    return {
+        ...base,
+        ...override,
+        worker: workerOverride === undefined
+            ? base.worker
+            : {
+                ...base.worker,
+                ...workerOverride,
+            },
+    };
+};
 const DEFAULTS = Object.freeze({
     enabled: false,
     connection: undefined,
@@ -160,6 +173,17 @@ const DEFAULTS = Object.freeze({
     captureCachePayloads: false,
     captureQueryBindings: true,
     logMinLevel: 'info',
+    contentDispatch: {
+        driver: undefined,
+        queueName: 'trace-content',
+        enqueueTimeoutMs: 25,
+        worker: {
+            enabled: true,
+            intervalMs: 1000,
+            maxDurationMs: 250,
+            concurrency: 1,
+        },
+    },
     watchers: {},
     redaction: {
         keys: [
@@ -222,6 +246,7 @@ export const TraceConfig = Object.freeze({
         return Object.freeze({
             ...DEFAULTS,
             ...overrides,
+            contentDispatch: mergeContentDispatch(DEFAULTS.contentDispatch, overrides.contentDispatch),
             watchers: mergeWatchers(DEFAULTS.watchers, overrides.watchers),
             redaction: {
                 keys: mergeStringLists(DEFAULTS.redaction.keys, overrides.redaction?.keys),

package/dist/index.d.ts

@@ -40,4 +40,4 @@ export declare const captureTraceException: (error: unknown, context?: {
     userId?: string;
 }) => void;
 export { EntryType } from './types';
-export type { AuthContent, BatchContent, CacheContent, ClientRequestContent, CommandContent, DumpContent, EntryTypeValue, EventContent, ExceptionContent, GateContent, ITraceConfig, ITraceEntry, ITraceWatcher, ITraceWatcherConfig, JobContent, LogContent, MailContent, MiddlewareContent, ModelContent, NotificationContent, QueryContent, RedactionConfig, RedisContent, RequestContent, ScheduleContent, TraceConfigOverrides, ViewContent, WatcherToggles, } from './types';
+export type { AuthContent, BatchContent, CacheContent, ClientRequestContent, CommandContent, DumpContent, EntryTypeValue, EventContent, ExceptionContent, GateContent, ITraceConfig, ITraceEntry, ITraceWatcher, ITraceWatcherConfig, JobContent, LogContent, MailContent, MiddlewareContent, ModelContent, NotificationContent, QueryContent, RedactionConfig, RedisContent, RequestContent, ScheduleContent, TraceConfigOverrides, TraceContentDispatchConfig, TraceContentDispatchWorkerConfig, ViewContent, WatcherToggles, } from './types';

package/dist/register.js

@@ -206,6 +206,13 @@ if (!traceAlreadyInitialized && Env) {
         const logMinLevelRaw = Env.get('TRACE_LOG_LEVEL', '').trim();
         const captureCachePayloadsRaw = Env.get('TRACE_CACHE_PAYLOADS', '').trim();
         const captureQueryBindingsRaw = Env.get('TRACE_QUERY_BINDINGS', '').trim();
+        const contentDispatchDriverRaw = Env.get('TRACE_CONTENT_QUEUE_DRIVER', '').trim();
+        const contentDispatchQueueRaw = Env.get('TRACE_CONTENT_QUEUE_NAME', '').trim();
+        const contentDispatchEnqueueTimeoutRaw = Env.get('TRACE_CONTENT_QUEUE_ENQUEUE_TIMEOUT_MS', '').trim();
+        const contentDispatchWorkerEnabledRaw = Env.get('TRACE_CONTENT_QUEUE_WORKER_ENABLED', '').trim();
+        const contentDispatchWorkerIntervalRaw = Env.get('TRACE_CONTENT_QUEUE_WORKER_INTERVAL_MS', '').trim();
+        const contentDispatchWorkerDurationRaw = Env.get('TRACE_CONTENT_QUEUE_WORKER_MAX_DURATION_MS', '').trim();
+        const contentDispatchWorkerConcurrencyRaw = Env.get('TRACE_CONTENT_QUEUE_WORKER_CONCURRENCY', '').trim();
         const redactionKeys = parseEnvList(Env.get('TRACE_REDACT_KEYS', ''));
         const redactionHeaders = parseEnvList(Env.get('TRACE_REDACT_HEADERS', ''));
         const redactionBody = parseEnvList(Env.get('TRACE_REDACT_BODY', ''));
@@ -221,6 +228,26 @@ if (!traceAlreadyInitialized && Env) {
         const logMinLevel = (logMinLevelRaw === '' ? startupOverrides?.logMinLevel : logMinLevelRaw);
         const captureCachePayloads = parseEnvBool(captureCachePayloadsRaw) ?? startupOverrides?.captureCachePayloads;
         const captureQueryBindings = parseEnvBool(captureQueryBindingsRaw) ?? startupOverrides?.captureQueryBindings;
+        const contentDispatchDriver = contentDispatchDriverRaw === ''
+            ? startupOverrides?.contentDispatch?.driver
+            : contentDispatchDriverRaw;
+        const contentDispatchQueueName = contentDispatchQueueRaw === ''
+            ? startupOverrides?.contentDispatch?.queueName
+            : contentDispatchQueueRaw;
+        const contentDispatchEnqueueTimeout = contentDispatchEnqueueTimeoutRaw === ''
+            ? startupOverrides?.contentDispatch?.enqueueTimeoutMs
+            : Number.parseInt(contentDispatchEnqueueTimeoutRaw, 10);
+        const contentDispatchWorkerEnabled = parseEnvBool(contentDispatchWorkerEnabledRaw) ??
+            startupOverrides?.contentDispatch?.worker?.enabled;
+        const contentDispatchWorkerInterval = contentDispatchWorkerIntervalRaw === ''
+            ? startupOverrides?.contentDispatch?.worker?.intervalMs
+            : Number.parseInt(contentDispatchWorkerIntervalRaw, 10);
+        const contentDispatchWorkerDuration = contentDispatchWorkerDurationRaw === ''
+            ? startupOverrides?.contentDispatch?.worker?.maxDurationMs
+            : Number.parseInt(contentDispatchWorkerDurationRaw, 10);
+        const contentDispatchWorkerConcurrency = contentDispatchWorkerConcurrencyRaw === ''
+            ? startupOverrides?.contentDispatch?.worker?.concurrency
+            : Number.parseInt(contentDispatchWorkerConcurrencyRaw, 10);
         const redaction = buildTraceRedactionOverrides({
             startupOverrides,
             redactionBody,
@@ -228,6 +255,9 @@ if (!traceAlreadyInitialized && Env) {
             redactionKeys,
             redactionQuery,
         });
+        const defaultContentDispatch = TraceConfig.defaults().contentDispatch;
+        const startupContentDispatch = startupOverrides?.contentDispatch;
+        const startupContentDispatchWorker = startupContentDispatch?.worker;
         const config = TraceConfig.merge({
             ...startupOverrides,
             enabled,
@@ -241,6 +271,42 @@ if (!traceAlreadyInitialized && Env) {
                 : {}),
             ...(typeof captureCachePayloads === 'boolean' ? { captureCachePayloads } : {}),
             ...(typeof captureQueryBindings === 'boolean' ? { captureQueryBindings } : {}),
+            contentDispatch: {
+                ...defaultContentDispatch,
+                ...startupContentDispatch,
+                ...(typeof contentDispatchDriver === 'string' && contentDispatchDriver !== ''
+                    ? { driver: contentDispatchDriver }
+                    : {}),
+                ...(typeof contentDispatchQueueName === 'string' && contentDispatchQueueName !== ''
+                    ? { queueName: contentDispatchQueueName }
+                    : {}),
+                ...(typeof contentDispatchEnqueueTimeout === 'number' &&
+                    Number.isFinite(contentDispatchEnqueueTimeout)
+                    ? { enqueueTimeoutMs: contentDispatchEnqueueTimeout }
+                    : {}),
+                worker: {
+                    ...defaultContentDispatch.worker,
+                    ...startupContentDispatchWorker,
+                    enabled: typeof contentDispatchWorkerEnabled === 'boolean'
+                        ? contentDispatchWorkerEnabled
+                        : (startupContentDispatchWorker?.enabled ?? defaultContentDispatch.worker.enabled),
+                    intervalMs: typeof contentDispatchWorkerInterval === 'number' &&
+                        Number.isFinite(contentDispatchWorkerInterval)
+                        ? contentDispatchWorkerInterval
+                        : (startupContentDispatchWorker?.intervalMs ??
+                            defaultContentDispatch.worker.intervalMs),
+                    maxDurationMs: typeof contentDispatchWorkerDuration === 'number' &&
+                        Number.isFinite(contentDispatchWorkerDuration)
+                        ? contentDispatchWorkerDuration
+                        : (startupContentDispatchWorker?.maxDurationMs ??
+                            defaultContentDispatch.worker.maxDurationMs),
+                    concurrency: typeof contentDispatchWorkerConcurrency === 'number' &&
+                        Number.isFinite(contentDispatchWorkerConcurrency)
+                        ? contentDispatchWorkerConcurrency
+                        : (startupContentDispatchWorker?.concurrency ??
+                            defaultContentDispatch.worker.concurrency),
+                },
+            },
             logMinLevel,
             ...(redaction === undefined ? {} : { redaction }),
         });
@@ -257,7 +323,7 @@ if (!traceAlreadyInitialized && Env) {
             envKey: 'TRACE_QUERY_CONNECTION',
         });
         await assertTraceStorageReady(core, storageDb, resolvedConnectionName);
-        const storage = TraceWriteDiagnostics.wrapStorage(TraceContentBudget.wrapStorage(TraceContentRedaction.wrapStorage(TraceEntryFiltering.wrapStorage(TraceStorage.resolveStorage(storageDb), config), config.redaction)), {
+        const storage = TraceWriteDiagnostics.wrapStorage(TraceContentBudget.wrapStorage(TraceContentRedaction.wrapStorage(TraceEntryFiltering.wrapStorage(TraceStorage.resolveStorage(storageDb), config), config.redaction), config), {
             connectionName: resolvedConnectionName,
             logger: core.Logger,
         });

package/dist/storage/TraceContentBudget.d.ts

@@ -1,4 +1,39 @@
-import type { ITraceStorage } from '../types';
+import type { ITraceConfig, ITraceStorage } from '../types';
+type QueueApi = {
+    get(name?: string): {
+        enqueue<T = unknown>(queue: string, payload: T): Promise<string>;
+    };
+};
+type TimeoutManagerApi = {
+    withTimeout<T>(operation: () => Promise<T>, timeoutMs: number, operationName: string, timeoutHandler?: () => Promise<T>): Promise<T>;
+};
+type QueueWorkerApi = {
+    createQueueWorker<TPayload>(options: {
+        kindLabel: string;
+        defaultQueueName: string;
+        maxAttempts: number;
+        getLogFields?: (payload: {
+            id: string;
+            payload: TPayload;
+            attempts: number;
+        }) => Record<string, unknown>;
+        handle(payload: TPayload): Promise<void>;
+    }): {
+        runOnce(options?: {
+            queueName?: string;
+            driverName?: string;
+            maxItems?: number;
+            maxDurationMs?: number;
+            concurrency?: number;
+        }): Promise<number>;
+    };
+};
+type TraceContentBudgetRuntime = {
+    queue?: QueueApi | null;
+    timeoutManager?: TimeoutManagerApi | null;
+    queueWorkerApi?: QueueWorkerApi | null;
+};
 export declare const TraceContentBudget: Readonly<{
-    wrapStorage(storage: ITraceStorage): ITraceStorage;
+    wrapStorage(storage: ITraceStorage, config: ITraceConfig, runtime?: TraceContentBudgetRuntime): ITraceStorage;
 }>;
+export {};

package/dist/storage/TraceContentBudget.js

@@ -5,6 +5,7 @@ const DEFAULT_MAX_OBJECT_ENTRIES = 40;
 const DEFAULT_MAX_DEPTH = 6;
 const DROPPED_FIELD_MESSAGE = '[trace] Value dropped because the field exceeded the trace storage size limit.';
 const COMPACTED_CONTENT_MESSAGE = '[trace] Trace content was compacted because it exceeded the trace storage size limit.';
+const REPLACED_CONTENT_MESSAGE = 'Trace content exceeded budget and was replaced.';
 const encoder = new TextEncoder();
 const serializedSize = (value) => {
     try {
@@ -151,15 +152,209 @@ const fitPatchToBudget = (patch) => {
         content: fitContentToBudget(patch.content),
     };
 };
+const startedWorkerKeys = new Set();
+const closePort = (port) => {
+    if (typeof port.close === 'function') {
+        port.close();
+    }
+};
+const scheduleTask = (task) => {
+    if (typeof MessageChannel === 'function') {
+        const channel = new MessageChannel();
+        channel.port1.onmessage = () => {
+            channel.port1.onmessage = null;
+            closePort(channel.port1);
+            closePort(channel.port2);
+            void task().catch(() => undefined);
+        };
+        channel.port2.postMessage(undefined);
+        return;
+    }
+    Promise.resolve()
+        .then(() => {
+        void task().catch(() => undefined);
+    })
+        .catch(() => undefined);
+};
+const getReplacementContent = (content) => {
+    return {
+        __traceNotice: REPLACED_CONTENT_MESSAGE,
+        dropped: true,
+        valueType: describeValueType(content),
+    };
+};
+const replaceEntryContent = (entry) => ({
+    ...entry,
+    content: getReplacementContent(entry.content),
+});
+const replacePatchContent = (patch) => {
+    if (patch.content === undefined)
+        return patch;
+    return {
+        ...patch,
+        content: getReplacementContent(patch.content),
+    };
+};
+const shouldReplaceContent = (content) => {
+    return serializedSize(content) > DEFAULT_MAX_ENTRY_BYTES;
+};
+const hasQueueDispatch = (config) => {
+    const driver = config.contentDispatch.driver?.trim();
+    return typeof driver === 'string' && driver !== '';
+};
+const getCoreRuntime = async () => {
+    try {
+        const mod = (await import('@zintrust/core'));
+        return {
+            Queue: mod.Queue ?? null,
+            TimeoutManager: mod.TimeoutManager ?? null,
+        };
+    }
+    catch {
+        return {
+            Queue: null,
+            TimeoutManager: null,
+        };
+    }
+};
+const getQueueWorkerApi = async () => {
+    try {
+        const mod = (await import('@zintrust/workers'));
+        return typeof mod.createQueueWorker === 'function' ? mod : null;
+    }
+    catch {
+        return null;
+    }
+};
+const enqueueTraceDispatch = async (config, payload, runtime) => {
+    const driverName = config.contentDispatch.driver?.trim();
+    if (driverName === undefined || driverName === '')
+        return false;
+    const coreRuntime = runtime?.queue !== undefined || runtime?.timeoutManager !== undefined
+        ? {
+            Queue: runtime?.queue ?? null,
+            TimeoutManager: runtime?.timeoutManager ?? null,
+        }
+        : await getCoreRuntime();
+    const queueApi = coreRuntime.Queue;
+    if (queueApi === null)
+        return false;
+    try {
+        const driver = queueApi.get(driverName);
+        const timeoutMs = Math.max(1, config.contentDispatch.enqueueTimeoutMs);
+        if (coreRuntime.TimeoutManager === null) {
+            await driver.enqueue(config.contentDispatch.queueName, payload);
+        }
+        else {
+            await coreRuntime.TimeoutManager.withTimeout(() => driver.enqueue(config.contentDispatch.queueName, payload), timeoutMs, 'trace-content-dispatch-enqueue');
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const persistWriteFallback = async (storage, entry) => {
+    await storage.writeEntry(shouldReplaceContent(entry.content) ? replaceEntryContent(entry) : entry);
+};
+const persistUpdateFallback = async (storage, uuid, patch) => {
+    await storage.updateEntry(uuid, patch.content !== undefined && shouldReplaceContent(patch.content)
+        ? replacePatchContent(patch)
+        : patch);
+};
+const processQueuedMessage = async (storage, message) => {
+    if (message.operation === 'write') {
+        await storage.writeEntry(fitEntryToBudget(message.entry));
+        return;
+    }
+    await storage.updateEntry(message.uuid, fitPatchToBudget(message.patch));
+};
+const ensureWorkerTimer = (_key, timer) => {
+    const unrefable = timer;
+    if (typeof unrefable.unref === 'function') {
+        unrefable.unref();
+    }
+};
+const startInternalDispatchWorker = (storage, config, runtime) => {
+    if (!hasQueueDispatch(config) || config.contentDispatch.worker.enabled !== true)
+        return;
+    const driverName = config.contentDispatch.driver?.trim() ?? '';
+    const key = `${driverName}:${config.contentDispatch.queueName}`;
+    if (startedWorkerKeys.has(key))
+        return;
+    startedWorkerKeys.add(key);
+    scheduleTask(async () => {
+        const workersApi = runtime?.queueWorkerApi ?? (await getQueueWorkerApi());
+        if (workersApi === null) {
+            startedWorkerKeys.delete(key);
+            return;
+        }
+        let running = false;
+        const runWorker = async () => {
+            if (running)
+                return;
+            running = true;
+            try {
+                const worker = workersApi.createQueueWorker({
+                    kindLabel: 'trace-content-dispatch',
+                    defaultQueueName: config.contentDispatch.queueName,
+                    maxAttempts: 1,
+                    getLogFields: () => ({
+                        queueName: config.contentDispatch.queueName,
+                        driverName,
+                    }),
+                    handle: async (payload) => {
+                        await processQueuedMessage(storage, payload);
+                    },
+                });
+                await worker.runOnce({
+                    queueName: config.contentDispatch.queueName,
+                    driverName,
+                    maxDurationMs: Math.max(1, config.contentDispatch.worker.maxDurationMs),
+                    concurrency: Math.max(1, config.contentDispatch.worker.concurrency),
+                });
+            }
+            finally {
+                running = false;
+            }
+        };
+        await runWorker();
+        const intervalMs = Math.max(100, config.contentDispatch.worker.intervalMs);
+        ensureWorkerTimer(key, setInterval(() => {
+            void runWorker();
+        }, intervalMs));
+    });
+};
+const dispatchWrite = (storage, config, entry, runtime) => {
+    scheduleTask(async () => {
+        if (hasQueueDispatch(config)) {
+            const enqueued = await enqueueTraceDispatch(config, { operation: 'write', entry }, runtime);
+            if (enqueued)
+                return;
+        }
+        await persistWriteFallback(storage, entry);
+    });
+};
+const dispatchUpdate = (storage, config, uuid, patch, runtime) => {
+    scheduleTask(async () => {
+        if (hasQueueDispatch(config)) {
+            const enqueued = await enqueueTraceDispatch(config, { operation: 'update', uuid, patch }, runtime);
+            if (enqueued)
+                return;
+        }
+        await persistUpdateFallback(storage, uuid, patch);
+    });
+};
 export const TraceContentBudget = Object.freeze({
-    wrapStorage(storage) {
+    wrapStorage(storage, config, runtime) {
+        startInternalDispatchWorker(storage, config, runtime);
         return Object.freeze({
             ...storage,
             writeEntry: async (entry) => {
-                await storage.writeEntry(fitEntryToBudget(entry));
+                dispatchWrite(storage, config, entry, runtime);
             },
             updateEntry: async (uuid, patch) => {
-                await storage.updateEntry(uuid, fitPatchToBudget(patch));
+                dispatchUpdate(storage, config, uuid, patch, runtime);
             },
         });
     },

package/dist/types.d.ts

@@ -304,6 +304,18 @@ export type TraceRequestWatcherConfig = TraceFilterRule & {
 export type TraceClientRequestWatcherConfig = TraceClientRequestCaptureRule & {
     sources?: Record<string, TraceClientRequestCaptureRule>;
 };
+export type TraceContentDispatchWorkerConfig = {
+    enabled: boolean;
+    intervalMs: number;
+    maxDurationMs: number;
+    concurrency: number;
+};
+export type TraceContentDispatchConfig = {
+    driver?: string;
+    queueName: string;
+    enqueueTimeoutMs: number;
+    worker: TraceContentDispatchWorkerConfig;
+};
 export type TraceWatcherToggle = boolean | TraceFilterRule;
 export type TraceRequestWatcherToggle = boolean | TraceRequestWatcherConfig;
 export type TraceClientRequestWatcherToggle = boolean | TraceClientRequestWatcherConfig;
@@ -339,6 +351,7 @@ export interface ITraceConfig {
     captureCachePayloads: boolean;
     captureQueryBindings: boolean;
     logMinLevel: 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+    contentDispatch: TraceContentDispatchConfig;
     watchers: WatcherToggles;
     redaction: RedactionConfig;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zintrust/trace",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "description": "Trace assistant for ZinTrust: logs requests, queries, exceptions, jobs, and more.",
   "private": false,
   "type": "module",
@@ -40,7 +40,7 @@
     "node": ">=20.0.0"
   },
   "peerDependencies": {
-    "@zintrust/core": "^0.5.1"
+    "@zintrust/core": "^0.5.2"
   },
   "publishConfig": {
     "access": "public"
@@ -56,4 +56,4 @@
     "build": "tsc -p tsconfig.json && tsc -p tsconfig.migrations.json && node ../../scripts/fix-dist-esm-imports.mjs dist",
     "prepublishOnly": "npm run build"
   }
-}
+}

package/src/config.ts

@@ -6,6 +6,7 @@ import type {
   TraceClientRequestCaptureRule,
   TraceClientRequestWatcherToggle,
   TraceConfigOverrides,
+  TraceContentDispatchConfig,
   TraceFilterRule,
   TraceRequestWatcherConfig,
   TraceWatcherToggle,
@@ -233,6 +234,25 @@ const mergeWatchers = (
   };
 };
 
+const mergeContentDispatch = (
+  base: TraceContentDispatchConfig,
+  override?: TraceConfigOverrides['contentDispatch']
+): TraceContentDispatchConfig => {
+  const workerOverride = override?.worker;
+
+  return {
+    ...base,
+    ...override,
+    worker:
+      workerOverride === undefined
+        ? base.worker
+        : {
+            ...base.worker,
+            ...workerOverride,
+          },
+  };
+};
+
 const DEFAULTS: ITraceConfig = Object.freeze({
   enabled: false,
   connection: undefined,
@@ -243,6 +263,17 @@ const DEFAULTS: ITraceConfig = Object.freeze({
   captureCachePayloads: false,
   captureQueryBindings: true,
   logMinLevel: 'info',
+  contentDispatch: {
+    driver: undefined,
+    queueName: 'trace-content',
+    enqueueTimeoutMs: 25,
+    worker: {
+      enabled: true,
+      intervalMs: 1000,
+      maxDurationMs: 250,
+      concurrency: 1,
+    },
+  },
   watchers: {},
   redaction: {
     keys: [
@@ -310,6 +341,7 @@ export const TraceConfig = Object.freeze({
     return Object.freeze({
       ...DEFAULTS,
       ...overrides,
+      contentDispatch: mergeContentDispatch(DEFAULTS.contentDispatch, overrides.contentDispatch),
       watchers: mergeWatchers(DEFAULTS.watchers, overrides.watchers),
       redaction: {
         keys: mergeStringLists(DEFAULTS.redaction.keys, overrides.redaction?.keys),

package/src/index.ts

@@ -94,6 +94,8 @@ export type {
   RequestContent,
   ScheduleContent,
   TraceConfigOverrides,
+  TraceContentDispatchConfig,
+  TraceContentDispatchWorkerConfig,
   ViewContent,
   WatcherToggles,
 } from './types';

package/src/register.ts

@@ -309,6 +309,28 @@ if (!traceAlreadyInitialized && Env) {
     const logMinLevelRaw = Env.get('TRACE_LOG_LEVEL', '').trim();
     const captureCachePayloadsRaw = Env.get('TRACE_CACHE_PAYLOADS', '').trim();
     const captureQueryBindingsRaw = Env.get('TRACE_QUERY_BINDINGS', '').trim();
+    const contentDispatchDriverRaw = Env.get('TRACE_CONTENT_QUEUE_DRIVER', '').trim();
+    const contentDispatchQueueRaw = Env.get('TRACE_CONTENT_QUEUE_NAME', '').trim();
+    const contentDispatchEnqueueTimeoutRaw = Env.get(
+      'TRACE_CONTENT_QUEUE_ENQUEUE_TIMEOUT_MS',
+      ''
+    ).trim();
+    const contentDispatchWorkerEnabledRaw = Env.get(
+      'TRACE_CONTENT_QUEUE_WORKER_ENABLED',
+      ''
+    ).trim();
+    const contentDispatchWorkerIntervalRaw = Env.get(
+      'TRACE_CONTENT_QUEUE_WORKER_INTERVAL_MS',
+      ''
+    ).trim();
+    const contentDispatchWorkerDurationRaw = Env.get(
+      'TRACE_CONTENT_QUEUE_WORKER_MAX_DURATION_MS',
+      ''
+    ).trim();
+    const contentDispatchWorkerConcurrencyRaw = Env.get(
+      'TRACE_CONTENT_QUEUE_WORKER_CONCURRENCY',
+      ''
+    ).trim();
     const redactionKeys = parseEnvList(Env.get('TRACE_REDACT_KEYS', ''));
     const redactionHeaders = parseEnvList(Env.get('TRACE_REDACT_HEADERS', ''));
     const redactionBody = parseEnvList(Env.get('TRACE_REDACT_BODY', ''));
@@ -335,6 +357,33 @@ if (!traceAlreadyInitialized && Env) {
       parseEnvBool(captureCachePayloadsRaw) ?? startupOverrides?.captureCachePayloads;
     const captureQueryBindings =
       parseEnvBool(captureQueryBindingsRaw) ?? startupOverrides?.captureQueryBindings;
+    const contentDispatchDriver =
+      contentDispatchDriverRaw === ''
+        ? startupOverrides?.contentDispatch?.driver
+        : contentDispatchDriverRaw;
+    const contentDispatchQueueName =
+      contentDispatchQueueRaw === ''
+        ? startupOverrides?.contentDispatch?.queueName
+        : contentDispatchQueueRaw;
+    const contentDispatchEnqueueTimeout =
+      contentDispatchEnqueueTimeoutRaw === ''
+        ? startupOverrides?.contentDispatch?.enqueueTimeoutMs
+        : Number.parseInt(contentDispatchEnqueueTimeoutRaw, 10);
+    const contentDispatchWorkerEnabled =
+      parseEnvBool(contentDispatchWorkerEnabledRaw) ??
+      startupOverrides?.contentDispatch?.worker?.enabled;
+    const contentDispatchWorkerInterval =
+      contentDispatchWorkerIntervalRaw === ''
+        ? startupOverrides?.contentDispatch?.worker?.intervalMs
+        : Number.parseInt(contentDispatchWorkerIntervalRaw, 10);
+    const contentDispatchWorkerDuration =
+      contentDispatchWorkerDurationRaw === ''
+        ? startupOverrides?.contentDispatch?.worker?.maxDurationMs
+        : Number.parseInt(contentDispatchWorkerDurationRaw, 10);
+    const contentDispatchWorkerConcurrency =
+      contentDispatchWorkerConcurrencyRaw === ''
+        ? startupOverrides?.contentDispatch?.worker?.concurrency
+        : Number.parseInt(contentDispatchWorkerConcurrencyRaw, 10);
     const redaction = buildTraceRedactionOverrides({
       startupOverrides,
       redactionBody,
@@ -342,6 +391,9 @@ if (!traceAlreadyInitialized && Env) {
       redactionKeys,
       redactionQuery,
     });
+    const defaultContentDispatch = TraceConfig.defaults().contentDispatch;
+    const startupContentDispatch = startupOverrides?.contentDispatch;
+    const startupContentDispatchWorker = startupContentDispatch?.worker;
 
     const config = TraceConfig.merge({
       ...startupOverrides,
@@ -356,6 +408,46 @@ if (!traceAlreadyInitialized && Env) {
         : {}),
       ...(typeof captureCachePayloads === 'boolean' ? { captureCachePayloads } : {}),
       ...(typeof captureQueryBindings === 'boolean' ? { captureQueryBindings } : {}),
+      contentDispatch: {
+        ...defaultContentDispatch,
+        ...startupContentDispatch,
+        ...(typeof contentDispatchDriver === 'string' && contentDispatchDriver !== ''
+          ? { driver: contentDispatchDriver }
+          : {}),
+        ...(typeof contentDispatchQueueName === 'string' && contentDispatchQueueName !== ''
+          ? { queueName: contentDispatchQueueName }
+          : {}),
+        ...(typeof contentDispatchEnqueueTimeout === 'number' &&
+        Number.isFinite(contentDispatchEnqueueTimeout)
+          ? { enqueueTimeoutMs: contentDispatchEnqueueTimeout }
+          : {}),
+        worker: {
+          ...defaultContentDispatch.worker,
+          ...startupContentDispatchWorker,
+          enabled:
+            typeof contentDispatchWorkerEnabled === 'boolean'
+              ? contentDispatchWorkerEnabled
+              : (startupContentDispatchWorker?.enabled ?? defaultContentDispatch.worker.enabled),
+          intervalMs:
+            typeof contentDispatchWorkerInterval === 'number' &&
+            Number.isFinite(contentDispatchWorkerInterval)
+              ? contentDispatchWorkerInterval
+              : (startupContentDispatchWorker?.intervalMs ??
+                defaultContentDispatch.worker.intervalMs),
+          maxDurationMs:
+            typeof contentDispatchWorkerDuration === 'number' &&
+            Number.isFinite(contentDispatchWorkerDuration)
+              ? contentDispatchWorkerDuration
+              : (startupContentDispatchWorker?.maxDurationMs ??
+                defaultContentDispatch.worker.maxDurationMs),
+          concurrency:
+            typeof contentDispatchWorkerConcurrency === 'number' &&
+            Number.isFinite(contentDispatchWorkerConcurrency)
+              ? contentDispatchWorkerConcurrency
+              : (startupContentDispatchWorker?.concurrency ??
+                defaultContentDispatch.worker.concurrency),
+        },
+      },
       logMinLevel,
       ...(redaction === undefined ? {} : { redaction }),
     });
@@ -384,7 +476,8 @@ if (!traceAlreadyInitialized && Env) {
         TraceContentRedaction.wrapStorage(
           TraceEntryFiltering.wrapStorage(TraceStorage.resolveStorage(storageDb), config),
           config.redaction
-        )
+        ),
+        config
       ),
       {
         connectionName: resolvedConnectionName,

package/src/storage/TraceContentBudget.ts

@@ -1,4 +1,4 @@
-import type { ITraceEntry, ITraceStorage } from '../types';
+import type { ITraceConfig, ITraceEntry, ITraceStorage } from '../types';
 
 const DEFAULT_MAX_ENTRY_BYTES = 64 * 1024;
 const DEFAULT_MAX_STRING_BYTES = 16 * 1024;
@@ -10,6 +10,7 @@ const DROPPED_FIELD_MESSAGE =
   '[trace] Value dropped because the field exceeded the trace storage size limit.';
 const COMPACTED_CONTENT_MESSAGE =
   '[trace] Trace content was compacted because it exceeded the trace storage size limit.';
+const REPLACED_CONTENT_MESSAGE = 'Trace content exceeded budget and was replaced.';
 
 const encoder = new TextEncoder();
 
@@ -208,18 +209,342 @@ const fitPatchToBudget = (
   };
 };
 
+type TraceDispatchMessage =
+  | { operation: 'write'; entry: ITraceEntry }
+  | {
+      operation: 'update';
+      uuid: string;
+      patch: Partial<Pick<ITraceEntry, 'content' | 'isLatest'>>;
+    };
+
+type QueueApi = {
+  get(name?: string): {
+    enqueue<T = unknown>(queue: string, payload: T): Promise<string>;
+  };
+};
+
+type TimeoutManagerApi = {
+  withTimeout<T>(
+    operation: () => Promise<T>,
+    timeoutMs: number,
+    operationName: string,
+    timeoutHandler?: () => Promise<T>
+  ): Promise<T>;
+};
+
+type QueueWorkerApi = {
+  createQueueWorker<TPayload>(options: {
+    kindLabel: string;
+    defaultQueueName: string;
+    maxAttempts: number;
+    getLogFields?: (payload: {
+      id: string;
+      payload: TPayload;
+      attempts: number;
+    }) => Record<string, unknown>;
+    handle(payload: TPayload): Promise<void>;
+  }): {
+    runOnce(options?: {
+      queueName?: string;
+      driverName?: string;
+      maxItems?: number;
+      maxDurationMs?: number;
+      concurrency?: number;
+    }): Promise<number>;
+  };
+};
+
+type UnrefableTimer = ReturnType<typeof setInterval> & { unref?: () => void };
+
+type TraceContentBudgetRuntime = {
+  queue?: QueueApi | null;
+  timeoutManager?: TimeoutManagerApi | null;
+  queueWorkerApi?: QueueWorkerApi | null;
+};
+
+const startedWorkerKeys = new Set<string>();
+
+const closePort = (port: MessagePort): void => {
+  if (typeof port.close === 'function') {
+    port.close();
+  }
+};
+
+const scheduleTask = (task: () => Promise<void>): void => {
+  if (typeof MessageChannel === 'function') {
+    const channel = new MessageChannel();
+
+    channel.port1.onmessage = (): void => {
+      channel.port1.onmessage = null;
+      closePort(channel.port1);
+      closePort(channel.port2);
+      void task().catch(() => undefined);
+    };
+
+    channel.port2.postMessage(undefined);
+    return;
+  }
+
+  Promise.resolve()
+    .then(() => {
+      void task().catch(() => undefined);
+    })
+    .catch(() => undefined);
+};
+
+const getReplacementContent = (content: unknown): Record<string, unknown> => {
+  return {
+    __traceNotice: REPLACED_CONTENT_MESSAGE,
+    dropped: true,
+    valueType: describeValueType(content),
+  };
+};
+
+const replaceEntryContent = (entry: ITraceEntry): ITraceEntry => ({
+  ...entry,
+  content: getReplacementContent(entry.content),
+});
+
+const replacePatchContent = (
+  patch: Partial<Pick<ITraceEntry, 'content' | 'isLatest'>>
+): Partial<Pick<ITraceEntry, 'content' | 'isLatest'>> => {
+  if (patch.content === undefined) return patch;
+
+  return {
+    ...patch,
+    content: getReplacementContent(patch.content),
+  };
+};
+
+const shouldReplaceContent = (content: unknown): boolean => {
+  return serializedSize(content) > DEFAULT_MAX_ENTRY_BYTES;
+};
+
+const hasQueueDispatch = (config: ITraceConfig): boolean => {
+  const driver = config.contentDispatch.driver?.trim();
+  return typeof driver === 'string' && driver !== '';
+};
+
+const getCoreRuntime = async (): Promise<{
+  Queue: QueueApi | null;
+  TimeoutManager: TimeoutManagerApi | null;
+}> => {
+  try {
+    const mod = (await import('@zintrust/core')) as unknown as {
+      Queue?: QueueApi;
+      TimeoutManager?: TimeoutManagerApi;
+    };
+    return {
+      Queue: mod.Queue ?? null,
+      TimeoutManager: mod.TimeoutManager ?? null,
+    };
+  } catch {
+    return {
+      Queue: null,
+      TimeoutManager: null,
+    };
+  }
+};
+
+const getQueueWorkerApi = async (): Promise<QueueWorkerApi | null> => {
+  try {
+    const mod = (await import('@zintrust/workers')) as unknown as QueueWorkerApi;
+    return typeof mod.createQueueWorker === 'function' ? mod : null;
+  } catch {
+    return null;
+  }
+};
+
+const enqueueTraceDispatch = async (
+  config: ITraceConfig,
+  payload: TraceDispatchMessage,
+  runtime?: TraceContentBudgetRuntime
+): Promise<boolean> => {
+  const driverName = config.contentDispatch.driver?.trim();
+  if (driverName === undefined || driverName === '') return false;
+
+  const coreRuntime =
+    runtime?.queue !== undefined || runtime?.timeoutManager !== undefined
+      ? {
+          Queue: runtime?.queue ?? null,
+          TimeoutManager: runtime?.timeoutManager ?? null,
+        }
+      : await getCoreRuntime();
+  const queueApi = coreRuntime.Queue;
+  if (queueApi === null) return false;
+
+  try {
+    const driver = queueApi.get(driverName);
+    const timeoutMs = Math.max(1, config.contentDispatch.enqueueTimeoutMs);
+    if (coreRuntime.TimeoutManager === null) {
+      await driver.enqueue(config.contentDispatch.queueName, payload);
+    } else {
+      await coreRuntime.TimeoutManager.withTimeout(
+        () => driver.enqueue(config.contentDispatch.queueName, payload),
+        timeoutMs,
+        'trace-content-dispatch-enqueue'
+      );
+    }
+
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+const persistWriteFallback = async (storage: ITraceStorage, entry: ITraceEntry): Promise<void> => {
+  await storage.writeEntry(
+    shouldReplaceContent(entry.content) ? replaceEntryContent(entry) : entry
+  );
+};
+
+const persistUpdateFallback = async (
+  storage: ITraceStorage,
+  uuid: string,
+  patch: Partial<Pick<ITraceEntry, 'content' | 'isLatest'>>
+): Promise<void> => {
+  await storage.updateEntry(
+    uuid,
+    patch.content !== undefined && shouldReplaceContent(patch.content)
+      ? replacePatchContent(patch)
+      : patch
+  );
+};
+
+const processQueuedMessage = async (
+  storage: ITraceStorage,
+  message: TraceDispatchMessage
+): Promise<void> => {
+  if (message.operation === 'write') {
+    await storage.writeEntry(fitEntryToBudget(message.entry));
+    return;
+  }
+
+  await storage.updateEntry(message.uuid, fitPatchToBudget(message.patch));
+};
+
+const ensureWorkerTimer = (_key: string, timer: ReturnType<typeof setInterval>): void => {
+  const unrefable = timer as UnrefableTimer;
+  if (typeof unrefable.unref === 'function') {
+    unrefable.unref();
+  }
+};
+
+const startInternalDispatchWorker = (
+  storage: ITraceStorage,
+  config: ITraceConfig,
+  runtime?: TraceContentBudgetRuntime
+): void => {
+  if (!hasQueueDispatch(config) || config.contentDispatch.worker.enabled !== true) return;
+
+  const driverName = config.contentDispatch.driver?.trim() ?? '';
+  const key = `${driverName}:${config.contentDispatch.queueName}`;
+  if (startedWorkerKeys.has(key)) return;
+  startedWorkerKeys.add(key);
+
+  scheduleTask(async () => {
+    const workersApi = runtime?.queueWorkerApi ?? (await getQueueWorkerApi());
+    if (workersApi === null) {
+      startedWorkerKeys.delete(key);
+      return;
+    }
+
+    let running = false;
+    const runWorker = async (): Promise<void> => {
+      if (running) return;
+      running = true;
+      try {
+        const worker = workersApi.createQueueWorker<TraceDispatchMessage>({
+          kindLabel: 'trace-content-dispatch',
+          defaultQueueName: config.contentDispatch.queueName,
+          maxAttempts: 1,
+          getLogFields: () => ({
+            queueName: config.contentDispatch.queueName,
+            driverName,
+          }),
+          handle: async (payload) => {
+            await processQueuedMessage(storage, payload);
+          },
+        });
+
+        await worker.runOnce({
+          queueName: config.contentDispatch.queueName,
+          driverName,
+          maxDurationMs: Math.max(1, config.contentDispatch.worker.maxDurationMs),
+          concurrency: Math.max(1, config.contentDispatch.worker.concurrency),
+        });
+      } finally {
+        running = false;
+      }
+    };
+
+    await runWorker();
+
+    const intervalMs = Math.max(100, config.contentDispatch.worker.intervalMs);
+    ensureWorkerTimer(
+      key,
+      setInterval(() => {
+        void runWorker();
+      }, intervalMs)
+    );
+  });
+};
+
+const dispatchWrite = (
+  storage: ITraceStorage,
+  config: ITraceConfig,
+  entry: ITraceEntry,
+  runtime?: TraceContentBudgetRuntime
+): void => {
+  scheduleTask(async () => {
+    if (hasQueueDispatch(config)) {
+      const enqueued = await enqueueTraceDispatch(config, { operation: 'write', entry }, runtime);
+      if (enqueued) return;
+    }
+
+    await persistWriteFallback(storage, entry);
+  });
+};
+
+const dispatchUpdate = (
+  storage: ITraceStorage,
+  config: ITraceConfig,
+  uuid: string,
+  patch: Partial<Pick<ITraceEntry, 'content' | 'isLatest'>>,
+  runtime?: TraceContentBudgetRuntime
+): void => {
+  scheduleTask(async () => {
+    if (hasQueueDispatch(config)) {
+      const enqueued = await enqueueTraceDispatch(
+        config,
+        { operation: 'update', uuid, patch },
+        runtime
+      );
+      if (enqueued) return;
+    }
+
+    await persistUpdateFallback(storage, uuid, patch);
+  });
+};
+
 export const TraceContentBudget = Object.freeze({
-  wrapStorage(storage: ITraceStorage): ITraceStorage {
+  wrapStorage(
+    storage: ITraceStorage,
+    config: ITraceConfig,
+    runtime?: TraceContentBudgetRuntime
+  ): ITraceStorage {
+    startInternalDispatchWorker(storage, config, runtime);
+
     return Object.freeze({
       ...storage,
       writeEntry: async (entry: ITraceEntry): Promise<void> => {
-        await storage.writeEntry(fitEntryToBudget(entry));
+        dispatchWrite(storage, config, entry, runtime);
       },
       updateEntry: async (
         uuid: string,
         patch: Partial<Pick<ITraceEntry, 'content' | 'isLatest'>>
       ): Promise<void> => {
-        await storage.updateEntry(uuid, fitPatchToBudget(patch));
+        dispatchUpdate(storage, config, uuid, patch, runtime);
       },
     });
   },

package/src/types.ts

@@ -359,6 +359,20 @@ export type TraceClientRequestWatcherConfig = TraceClientRequestCaptureRule & {
   sources?: Record<string, TraceClientRequestCaptureRule>;
 };
 
+export type TraceContentDispatchWorkerConfig = {
+  enabled: boolean;
+  intervalMs: number;
+  maxDurationMs: number;
+  concurrency: number;
+};
+
+export type TraceContentDispatchConfig = {
+  driver?: string;
+  queueName: string;
+  enqueueTimeoutMs: number;
+  worker: TraceContentDispatchWorkerConfig;
+};
+
 export type TraceWatcherToggle = boolean | TraceFilterRule;
 export type TraceRequestWatcherToggle = boolean | TraceRequestWatcherConfig;
 export type TraceClientRequestWatcherToggle = boolean | TraceClientRequestWatcherConfig;
@@ -396,6 +410,7 @@ export interface ITraceConfig {
   captureCachePayloads: boolean;
   captureQueryBindings: boolean;
   logMinLevel: 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+  contentDispatch: TraceContentDispatchConfig;
   watchers: WatcherToggles;
   redaction: RedactionConfig;
 }