@zintrust/trace 0.5.2 → 0.5.5

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 {
@@ -21,58 +22,6 @@ const describeValueType = (value) => {
         return 'null';
     return typeof value;
 };
-const chooseLargerCandidate = (left, right) => {
-    if (left === null)
-        return right;
-    if (right === null)
-        return left;
-    return right.size > left.size ? right : left;
-};
-const fallbackCandidate = (value, path) => {
-    return path.length === 0 ? null : { path, size: serializedSize(value) };
-};
-const findLargestDroppablePathInArray = (value, path) => {
-    let best = null;
-    for (const [index, item] of value.entries()) {
-        best = chooseLargerCandidate(best, findLargestDroppablePath(item, [...path, index]));
-    }
-    return best ?? fallbackCandidate(value, path);
-};
-const findLargestDroppablePathInObject = (value, path) => {
-    let best = null;
-    for (const [key, entryValue] of Object.entries(value)) {
-        if (key === '__traceNotice')
-            continue;
-        best = chooseLargerCandidate(best, findLargestDroppablePath(entryValue, [...path, key]));
-    }
-    return best ?? fallbackCandidate(value, path);
-};
-const findLargestDroppablePath = (value, path = []) => {
-    if (Array.isArray(value))
-        return findLargestDroppablePathInArray(value, path);
-    if (typeof value === 'object' && value !== null) {
-        return findLargestDroppablePathInObject(value, path);
-    }
-    return fallbackCandidate(value, path);
-};
-const replaceAtPath = (value, path, replacement) => {
-    if (path.length === 0)
-        return replacement;
-    const [segment, ...rest] = path;
-    if (Array.isArray(value) && typeof segment === 'number') {
-        const next = value.slice();
-        next[segment] = replaceAtPath(next[segment], rest, replacement);
-        return next;
-    }
-    if (typeof value === 'object' && value !== null && typeof segment === 'string') {
-        const current = value;
-        return {
-            ...current,
-            [segment]: replaceAtPath(current[segment], rest, replacement),
-        };
-    }
-    return value;
-};
 const compactValue = (value, depth) => {
     if (depth >= DEFAULT_MAX_DEPTH) {
         return DROPPED_FIELD_MESSAGE;
@@ -105,17 +54,28 @@ const compactValue = (value, depth) => {
     return Object.fromEntries(compactedEntries);
 };
 const compactStructuredValueToBudget = (value) => {
-    let compacted = typeof value === 'object' && value !== null && !Array.isArray(value)
-        ? {
-            ...value,
-            __traceNotice: COMPACTED_CONTENT_MESSAGE,
-        }
-        : value;
-    while (serializedSize(compacted) > DEFAULT_MAX_ENTRY_BYTES) {
-        const candidate = findLargestDroppablePath(compacted);
-        if (candidate === null)
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return value;
+    }
+    const compacted = {
+        ...value,
+        __traceNotice: COMPACTED_CONTENT_MESSAGE,
+    };
+    const topLevelCandidates = Object.entries(compacted)
+        .filter(([key]) => key !== '__traceNotice')
+        .map(([key, entryValue]) => ({ key, size: serializedSize(entryValue) }))
+        .sort((left, right) => right.size - left.size);
+    let droppedCount = 0;
+    for (const candidate of topLevelCandidates) {
+        if (serializedSize(compacted) <= DEFAULT_MAX_ENTRY_BYTES) {
             break;
-        compacted = replaceAtPath(compacted, candidate.path, DROPPED_FIELD_MESSAGE);
+        }
+        compacted[candidate.key] = DROPPED_FIELD_MESSAGE;
+        droppedCount += 1;
+    }
+    if (droppedCount > 0) {
+        compacted['__traceNotice'] =
+            `${COMPACTED_CONTENT_MESSAGE} ${String(droppedCount)} top-level field(s) were dropped.`;
     }
     return compacted;
 };
@@ -151,15 +111,212 @@ const fitPatchToBudget = (patch) => {
         content: fitContentToBudget(patch.content),
     };
 };
+const startedWorkerKeys = new Set();
+const closePort = (port) => {
+    if (typeof port.close === 'function') {
+        port.close();
+    }
+};
+const scheduleTask = async (task) => {
+    return await new Promise((resolve, reject) => {
+        const runTask = () => {
+            void task().then(resolve).catch(reject);
+        };
+        if (typeof MessageChannel === 'function') {
+            const channel = new MessageChannel();
+            channel.port1.onmessage = () => {
+                channel.port1.onmessage = null;
+                closePort(channel.port1);
+                closePort(channel.port2);
+                runTask();
+            };
+            channel.port2.postMessage(undefined);
+            return;
+        }
+        Promise.resolve().then(runTask).catch(reject);
+    });
+};
+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);
+    void 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));
+    }).catch(() => {
+        startedWorkerKeys.delete(key);
+    });
+};
+const dispatchWrite = async (storage, config, entry, runtime) => {
+    await scheduleTask(async () => {
+        if (hasQueueDispatch(config)) {
+            const enqueued = await enqueueTraceDispatch(config, { operation: 'write', entry }, runtime);
+            if (enqueued)
+                return;
+        }
+        await persistWriteFallback(storage, entry);
+    });
+};
+const dispatchUpdate = async (storage, config, uuid, patch, runtime) => {
+    await 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));
+                await dispatchWrite(storage, config, entry, runtime);
             },
             updateEntry: async (uuid, patch) => {
-                await storage.updateEntry(uuid, fitPatchToBudget(patch));
+                await 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;
 }