@zintrust/trace 0.4.76 → 0.4.79

package/dist/storage/TraceStorage.js

@@ -3,6 +3,38 @@ const TABLE_ENTRIES = 'zin_trace_entries';
 const TABLE_TAGS = 'zin_trace_entries_tags';
 const TABLE_MONITORING = 'zin_trace_monitoring';
 const generateUuid = () => crypto.randomUUID();
+const buildIgnoreInsert = (db, table, columns, conflictColumns) => {
+    const columnList = columns.join(', ');
+    const placeholders = columns.map(() => '?').join(', ');
+    const driver = db.getType?.() ?? 'sqlite';
+    if (driver === 'sqlite' || driver === 'd1' || driver === 'd1-remote') {
+        return `INSERT OR IGNORE INTO ${table} (${columnList}) VALUES (${placeholders})`;
+    }
+    if (driver === 'mysql') {
+        return `INSERT IGNORE INTO ${table} (${columnList}) VALUES (${placeholders})`;
+    }
+    if (driver === 'postgresql') {
+        return `INSERT INTO ${table} (${columnList}) VALUES (${placeholders}) ON CONFLICT (${conflictColumns.join(', ')}) DO NOTHING`;
+    }
+    if (driver === 'sqlserver') {
+        const sourceColumns = columns.map((_, index) => `v${index + 1}`);
+        const selectClause = sourceColumns.map((name) => `? AS ${name}`).join(', ');
+        const conflictClause = conflictColumns
+            .map((column) => `target.${column} = source.${column}`)
+            .join(' AND ');
+        const insertValues = columns.map((column) => `source.${column}`).join(', ');
+        const sourceProjection = columns
+            .map((column, index) => `${sourceColumns[index]} AS ${column}`)
+            .join(', ');
+        return [
+            `MERGE INTO ${table} WITH (HOLDLOCK) AS target`,
+            `USING (SELECT ${sourceProjection} FROM (SELECT ${selectClause}) seed) AS source`,
+            `ON ${conflictClause}`,
+            `WHEN NOT MATCHED THEN INSERT (${columnList}) VALUES (${insertValues});`,
+        ].join(' ');
+    }
+    return `INSERT INTO ${table} (${columnList}) VALUES (${placeholders})`;
+};
 const rowToEntry = (row, tags) => ({
     uuid: row.uuid,
     batchId: row.batch_id,
@@ -16,11 +48,9 @@ const rowToEntry = (row, tags) => ({
 const insertTags = async (db, uuid, tags) => {
     if (tags.length === 0)
         return;
+    const sql = buildIgnoreInsert(db, TABLE_TAGS, ['entry_uuid', 'tag'], ['entry_uuid', 'tag']);
     await Promise.all(tags.map(async (tag) => {
-        await db.execute(`INSERT OR IGNORE INTO ${TABLE_TAGS} (entry_uuid, tag) VALUES (?, ?)`, [
-            uuid,
-            tag,
-        ]);
+        await db.execute(sql, [uuid, tag]);
     }));
 };
 const buildEntryFilters = (opts) => {
@@ -158,7 +188,7 @@ const createStorage = (db) => {
         return rows.map((row) => row.tag);
     };
     const addMonitoring = async (tag) => {
-        await db.execute(`INSERT OR IGNORE INTO ${TABLE_MONITORING} (tag) VALUES (?)`, [tag]);
+        await db.execute(buildIgnoreInsert(db, TABLE_MONITORING, ['tag'], ['tag']), [tag]);
     };
     const removeMonitoring = async (tag) => {
         await db.execute(`DELETE FROM ${TABLE_MONITORING} WHERE tag = ?`, [tag]);

package/dist/storage/TraceWriteDiagnostics.d.ts

@@ -0,0 +1,19 @@
+import type { ITraceStorage } from '../types';
+type TraceLogger = {
+    warn: (message: string, context?: Record<string, unknown>) => void;
+};
+type TraceWriteDiagnosticsSnapshot = {
+    degraded: boolean;
+    lastErrorMessage: string | null;
+    lastFailureAt: number | null;
+    totalFailures: number;
+};
+export declare const TraceWriteDiagnostics: Readonly<{
+    getSnapshot(): TraceWriteDiagnosticsSnapshot;
+    reset(): void;
+    wrapStorage(storage: ITraceStorage, options: {
+        connectionName: string;
+        logger?: TraceLogger;
+    }): ITraceStorage;
+}>;
+export {};

package/dist/storage/TraceWriteDiagnostics.js

@@ -0,0 +1,98 @@
+const LOG_WINDOW_MS = 30_000;
+const diagnosticsState = {
+    degraded: false,
+    lastErrorMessage: null,
+    lastFailureAt: null,
+    lastLoggedAtByFingerprint: new Map(),
+    totalFailures: 0,
+};
+const getErrorMessage = (error) => {
+    if (error instanceof Error && error.message.trim() !== '')
+        return error.message;
+    if (typeof error === 'string' && error.trim() !== '')
+        return error;
+    try {
+        const serialized = JSON.stringify(error);
+        if (typeof serialized === 'string' && serialized !== '')
+            return serialized;
+    }
+    catch {
+        // ignore serialization failures
+    }
+    return 'Unknown trace storage error';
+};
+const buildFingerprint = (context) => {
+    return [
+        context.connectionName,
+        context.operation,
+        context.watcherType ?? 'unknown',
+        getErrorMessage(context.error),
+    ].join('|');
+};
+const reportFailure = (logger, context) => {
+    const now = Date.now();
+    const errorMessage = getErrorMessage(context.error);
+    const fingerprint = buildFingerprint(context);
+    const lastLoggedAt = diagnosticsState.lastLoggedAtByFingerprint.get(fingerprint);
+    diagnosticsState.degraded = true;
+    diagnosticsState.lastErrorMessage = errorMessage;
+    diagnosticsState.lastFailureAt = now;
+    diagnosticsState.totalFailures += 1;
+    if (!logger)
+        return;
+    if (typeof lastLoggedAt === 'number' && now - lastLoggedAt < LOG_WINDOW_MS)
+        return;
+    diagnosticsState.lastLoggedAtByFingerprint.set(fingerprint, now);
+    logger.warn('[trace] Trace storage write degraded', {
+        connectionName: context.connectionName,
+        error: errorMessage,
+        lastFailureAt: now,
+        operation: context.operation,
+        totalFailures: diagnosticsState.totalFailures,
+        watcherType: context.watcherType ?? null,
+    });
+};
+const wrapStorageMethod = (method, describeFailure, connectionName, logger) => {
+    return async (...args) => {
+        try {
+            return await method(...args);
+        }
+        catch (error) {
+            reportFailure(logger, {
+                ...describeFailure(...args),
+                connectionName,
+                error,
+            });
+            throw error;
+        }
+    };
+};
+export const TraceWriteDiagnostics = Object.freeze({
+    getSnapshot() {
+        return {
+            degraded: diagnosticsState.degraded,
+            lastErrorMessage: diagnosticsState.lastErrorMessage,
+            lastFailureAt: diagnosticsState.lastFailureAt,
+            totalFailures: diagnosticsState.totalFailures,
+        };
+    },
+    reset() {
+        diagnosticsState.degraded = false;
+        diagnosticsState.lastErrorMessage = null;
+        diagnosticsState.lastFailureAt = null;
+        diagnosticsState.totalFailures = 0;
+        diagnosticsState.lastLoggedAtByFingerprint.clear();
+    },
+    wrapStorage(storage, options) {
+        return Object.freeze({
+            ...storage,
+            writeEntry: wrapStorageMethod(storage.writeEntry.bind(storage), (entry) => ({ operation: 'writeEntry', watcherType: entry.type }), options.connectionName, options.logger),
+            updateEntry: wrapStorageMethod(storage.updateEntry.bind(storage), (_uuid, _patch) => ({ operation: 'updateEntry' }), options.connectionName, options.logger),
+            markFamilyStale: wrapStorageMethod(storage.markFamilyStale.bind(storage), (_familyHash, _exceptUuid) => ({ operation: 'markFamilyStale' }), options.connectionName, options.logger),
+            prune: wrapStorageMethod(storage.prune.bind(storage), (_olderThanMs, _keepExceptions) => ({ operation: 'prune' }), options.connectionName, options.logger),
+            clear: wrapStorageMethod(storage.clear.bind(storage), () => ({ operation: 'clear' }), options.connectionName, options.logger),
+            addMonitoring: wrapStorageMethod(storage.addMonitoring.bind(storage), (_tag) => ({ operation: 'addMonitoring' }), options.connectionName, options.logger),
+            removeMonitoring: wrapStorageMethod(storage.removeMonitoring.bind(storage), (_tag) => ({ operation: 'removeMonitoring' }), options.connectionName, options.logger),
+        });
+    },
+});

package/dist/types.d.ts

@@ -30,9 +30,10 @@ export interface RequestContent {
     method: string;
     uri: string;
     headers: Record<string, string>;
-    payload: Record<string, unknown>;
+    payload: unknown;
     responseStatus: number;
     responseHeaders: Record<string, string>;
+    responseBody?: unknown;
     duration: number;
     memory: number | null;
     middleware: string[];
@@ -231,31 +232,47 @@ export interface ITraceWatcher {
     register(opts: ITraceWatcherConfig): () => void;
 }
 export type RedactionConfig = {
+    keys: string[];
     headers: string[];
     body: string[];
     query: string[];
 };
+export type TraceFilterRule = {
+    enabled?: boolean;
+    include?: string[];
+    exclude?: string[];
+};
+export type TraceRequestWatcherConfig = TraceFilterRule & {
+    all?: TraceFilterRule;
+    get?: TraceFilterRule;
+    post?: TraceFilterRule;
+    put?: TraceFilterRule;
+    patch?: TraceFilterRule;
+    delete?: TraceFilterRule;
+};
+export type TraceWatcherToggle = boolean | TraceFilterRule;
+export type TraceRequestWatcherToggle = boolean | TraceRequestWatcherConfig;
 export type WatcherToggles = {
-    request?: boolean;
-    query?: boolean;
-    exception?: boolean;
-    log?: boolean;
-    job?: boolean;
-    cache?: boolean;
-    schedule?: boolean;
-    mail?: boolean;
-    auth?: boolean;
-    event?: boolean;
-    model?: boolean;
-    notification?: boolean;
-    redis?: boolean;
-    gate?: boolean;
-    middleware?: boolean;
-    command?: boolean;
-    batch?: boolean;
-    dump?: boolean;
-    view?: boolean;
-    clientRequest?: boolean;
+    request?: TraceRequestWatcherToggle;
+    query?: TraceWatcherToggle;
+    exception?: TraceWatcherToggle;
+    log?: TraceWatcherToggle;
+    job?: TraceWatcherToggle;
+    cache?: TraceWatcherToggle;
+    schedule?: TraceWatcherToggle;
+    mail?: TraceWatcherToggle;
+    auth?: TraceWatcherToggle;
+    event?: TraceWatcherToggle;
+    model?: TraceWatcherToggle;
+    notification?: TraceWatcherToggle;
+    redis?: TraceWatcherToggle;
+    gate?: TraceWatcherToggle;
+    middleware?: TraceWatcherToggle;
+    command?: TraceWatcherToggle;
+    batch?: TraceWatcherToggle;
+    dump?: TraceWatcherToggle;
+    view?: TraceWatcherToggle;
+    clientRequest?: TraceWatcherToggle;
 };
 export interface ITraceConfig {
     enabled: boolean;

package/dist/utils/entryFilter.d.ts

@@ -0,0 +1,4 @@
+import type { ITraceConfig, ITraceEntry } from '../types';
+export declare const TraceEntryFilter: Readonly<{
+    shouldCapture(entry: ITraceEntry, config: ITraceConfig): boolean;
+}>;

package/dist/utils/entryFilter.js

@@ -0,0 +1,95 @@
+import { EntryType } from '../types.js';
+const isObjectValue = (value) => {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+};
+const normalizeTerms = (terms) => {
+    if (!Array.isArray(terms))
+        return [];
+    return terms
+        .filter((term) => typeof term === 'string')
+        .map((term) => term.trim().toLowerCase())
+        .filter((term) => term !== '');
+};
+const matchesRule = (haystack, rule) => {
+    if (!rule)
+        return true;
+    const include = normalizeTerms(rule.include);
+    const exclude = normalizeTerms(rule.exclude);
+    if (exclude.some((term) => haystack.includes(term)))
+        return false;
+    if (include.length === 0)
+        return true;
+    return include.some((term) => haystack.includes(term));
+};
+const toSearchableText = (entry) => {
+    const sections = [entry.type, entry.batchId, ...(entry.tags ?? [])];
+    try {
+        sections.push(JSON.stringify(entry.content) ?? '');
+    }
+    catch {
+        sections.push(String(entry.content ?? ''));
+    }
+    return sections.join(' ').toLowerCase();
+};
+const watcherKeyByEntryType = {
+    [EntryType.REQUEST]: 'request',
+    [EntryType.QUERY]: 'query',
+    [EntryType.EXCEPTION]: 'exception',
+    [EntryType.LOG]: 'log',
+    [EntryType.JOB]: 'job',
+    [EntryType.CACHE]: 'cache',
+    [EntryType.SCHEDULE]: 'schedule',
+    [EntryType.MAIL]: 'mail',
+    [EntryType.AUTH]: 'auth',
+    [EntryType.EVENT]: 'event',
+    [EntryType.MODEL]: 'model',
+    [EntryType.NOTIFICATION]: 'notification',
+    [EntryType.REDIS]: 'redis',
+    [EntryType.GATE]: 'gate',
+    [EntryType.MIDDLEWARE]: 'middleware',
+    [EntryType.COMMAND]: 'command',
+    [EntryType.BATCH]: 'batch',
+    [EntryType.DUMP]: 'dump',
+    [EntryType.VIEW]: 'view',
+    [EntryType.CLIENT_REQUEST]: 'clientRequest',
+};
+const getRequestMethodRule = (watcher, entry) => {
+    if (entry.type !== EntryType.REQUEST)
+        return undefined;
+    const content = isObjectValue(entry.content) ? entry.content : undefined;
+    const methodValue = content?.['method'];
+    const method = typeof methodValue === 'string' ? methodValue.trim().toLowerCase() : '';
+    if (method === 'get')
+        return watcher.get;
+    if (method === 'post')
+        return watcher.post;
+    if (method === 'put')
+        return watcher.put;
+    if (method === 'patch')
+        return watcher.patch;
+    if (method === 'delete' || method === 'del')
+        return watcher.delete;
+    return watcher.all;
+};
+export const TraceEntryFilter = Object.freeze({
+    shouldCapture(entry, config) {
+        const watcherKey = watcherKeyByEntryType[entry.type];
+        const watcher = config.watchers[watcherKey];
+        if (watcher === false)
+            return false;
+        if (!isObjectValue(watcher))
+            return true;
+        const haystack = toSearchableText(entry);
+        if (!matchesRule(haystack, watcher))
+            return false;
+        if (watcherKey === 'request') {
+            const requestWatcher = watcher;
+            const methodRule = getRequestMethodRule(requestWatcher, entry);
+            if (!matchesRule(haystack, requestWatcher.all))
+                return false;
+            if (!matchesRule(haystack, methodRule))
+                return false;
+        }
+        return true;
+    },
+});

package/dist/utils/redact.d.ts

@@ -2,5 +2,6 @@
  * Redaction helpers for @zintrust/trace watchers.
  */
 export declare const redactHeaders: (headers: Record<string, string>, fields: string[]) => Record<string, string>;
+export declare const redactUnknown: (value: unknown, fields: string[]) => unknown;
 export declare const redactObject: (obj: Record<string, unknown>, fields: string[]) => Record<string, unknown>;
 export declare const redactString: (value: string, fields: string[]) => string;

package/dist/utils/redact.js

@@ -1,7 +1,42 @@
 /**
  * Redaction helpers for @zintrust/trace watchers.
  */
-const REDACTED = '[REDACTED]';
+const REDACTED = '****';
+const isArrayValue = (value) => Array.isArray(value);
+const isObjectValue = (value) => {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+};
+const normalizeFields = (fields) => {
+    const normalized = new Set();
+    for (const field of fields) {
+        if (typeof field !== 'string')
+            continue;
+        const key = field.trim().toLowerCase();
+        if (key !== '')
+            normalized.add(key);
+    }
+    return normalized;
+};
+const redactUnknownValue = (value, fields, seen) => {
+    if (isArrayValue(value)) {
+        return value.map((item) => redactUnknownValue(item, fields, seen));
+    }
+    if (!isObjectValue(value)) {
+        return value;
+    }
+    if (seen.has(value)) {
+        return '[Circular]';
+    }
+    seen.add(value);
+    const out = {};
+    for (const [key, entryValue] of Object.entries(value)) {
+        out[key] = fields.has(key.toLowerCase())
+            ? REDACTED
+            : redactUnknownValue(entryValue, fields, seen);
+    }
+    seen.delete(value);
+    return out;
+};
 const redactQuerySegment = (segment, fields) => {
     const separatorIndex = segment.indexOf('=');
     if (separatorIndex <= 0)
@@ -13,23 +48,22 @@ const redactQuerySegment = (segment, fields) => {
     return `${key}=${REDACTED}`;
 };
 export const redactHeaders = (headers, fields) => {
-    const lower = new Set(fields.map((f) => f.toLowerCase()));
+    const lower = normalizeFields(fields);
     const out = {};
     for (const [k, v] of Object.entries(headers)) {
         out[k] = lower.has(k.toLowerCase()) ? REDACTED : v;
     }
     return out;
 };
+export const redactUnknown = (value, fields) => {
+    return redactUnknownValue(value, normalizeFields(fields), new WeakSet());
+};
 export const redactObject = (obj, fields) => {
-    const lower = new Set(fields.map((f) => f.toLowerCase()));
-    const out = {};
-    for (const [k, v] of Object.entries(obj)) {
-        out[k] = lower.has(k.toLowerCase()) ? REDACTED : v;
-    }
-    return out;
+    const redacted = redactUnknown(obj, fields);
+    return isObjectValue(redacted) ? redacted : {};
 };
 export const redactString = (value, fields) => {
-    const lower = new Set(fields.map((f) => f.toLowerCase()));
+    const lower = normalizeFields(fields);
     if (value === '')
         return value;
     let output = '';

package/dist/watchers/CommandWatcher.js

@@ -39,7 +39,7 @@ export const CommandWatcher = Object.freeze({
         if (config.watchers.command === false)
             return () => undefined;
         _storage = storage;
-        _redactKeys = config.redaction?.body ?? [];
+        _redactKeys = [...(config.redaction?.keys ?? []), ...(config.redaction?.body ?? [])];
         _ignoreRoutes = config.ignoreRoutes;
         return () => {
             _storage = null;

package/dist/watchers/ExceptionWatcher.d.ts

@@ -1,4 +1,11 @@
 import type { ITraceWatcher } from '../types';
+type ExceptionCaptureContext = {
+    batchId?: string;
+    hostname?: string;
+    path?: string;
+    userId?: string;
+};
 export declare const ExceptionWatcher: ITraceWatcher & {
-    capture: (err: unknown) => void;
+    capture: (err: unknown, context?: ExceptionCaptureContext) => void;
 };
+export {};

package/dist/watchers/ExceptionWatcher.js

@@ -13,7 +13,7 @@ import { parseStackFrameLine } from '../utils/stackFrame.js';
 const getLinePreview = (_file, _line) => {
     return {};
 };
-const buildContent = (err) => {
+const buildContent = (err, context) => {
     const stack = err.stack ?? '';
     const trace = stack
         .split('\n')
@@ -30,8 +30,8 @@ const buildContent = (err) => {
         trace,
         linePreview: firstFrame ? getLinePreview(firstFrame.file, firstFrame.line) : {},
         occurrences: 1,
-        hostname: TraceContext.getHostname(),
-        userId: TraceContext.getUserId(),
+        hostname: context?.hostname ?? TraceContext.getHostname(),
+        userId: context?.userId ?? TraceContext.getUserId(),
     };
 };
 let _storage = null;
@@ -55,21 +55,26 @@ const unregisterProcessListeners = () => {
     process.off('uncaughtException', handleUncaughtException);
     process.off('unhandledRejection', handleUnhandledRejection);
 };
-const captureException = (err) => {
+const captureException = (err, context) => {
     const storage = _storage;
     if (!storage)
         return;
     if (!(err instanceof Error))
         return;
-    if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes))
+    if (context?.path !== undefined) {
+        if (RequestFilter.matchesIgnoredPath(context.path, _ignoreRoutes))
+            return;
+    }
+    else if (RequestFilter.shouldIgnoreCurrentRequest(_ignoreRoutes)) {
         return;
-    const content = buildContent(err);
+    }
+    const content = buildContent(err, context);
     const hash = familyHash(`${content.class}:${content.file}:${content.line}`);
     const uuid = crypto.randomUUID();
     storage
         .writeEntry({
         uuid,
-        batchId: TraceContext.getBatchId(),
+        batchId: context?.batchId ?? TraceContext.getBatchId(),
         familyHash: hash,
         type: EntryType.EXCEPTION,
         content,

package/dist/watchers/HttpClientWatcher.js

@@ -40,7 +40,7 @@ export const HttpClientWatcher = Object.freeze({
         if (config.watchers.clientRequest === false)
             return () => undefined;
         _storage = storage;
-        _redactHeaderNames = config.redaction?.headers ?? [];
+        _redactHeaderNames = [...(config.redaction?.keys ?? []), ...(config.redaction?.headers ?? [])];
         _ignoreRoutes = config.ignoreRoutes;
         return () => {
             _storage = null;