jxp 4.1.1 → 4.2.0

package/dist/libs/index_diagnostics.js

@@ -0,0 +1,671 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.INDEX_QUERY_LOG_MODEL_NAME = exports.SYNC_CONFIRM_PHRASE = void 0;
+exports.shouldMonitorQuery = shouldMonitorQuery;
+exports.summarizeFilter = summarizeFilter;
+exports.extractScanStagePath = extractScanStagePath;
+exports.formatScanStagePath = formatScanStagePath;
+exports.hasCollScan = hasCollScan;
+exports.classifyExplain = classifyExplain;
+exports.auditModel = auditModel;
+exports.auditAllModels = auditAllModels;
+exports.syncAllModels = syncAllModels;
+exports.loadModelsFromDir = loadModelsFromDir;
+exports.wireQueryLogPersistence = wireQueryLogPersistence;
+exports.resolveIndexDiagnosticsConfig = resolveIndexDiagnosticsConfig;
+exports.setQueryLogModel = setQueryLogModel;
+exports.setPersistQueries = setPersistQueries;
+exports.getQueryMonitorBuffer = getQueryMonitorBuffer;
+exports.getQueryMonitorStatus = getQueryMonitorStatus;
+exports.listQueryLogs = listQueryLogs;
+exports.getQueryMonitorConfig = getQueryMonitorConfig;
+exports.registerQueryIndexMonitor = registerQueryIndexMonitor;
+exports.getCachedIndexAudit = getCachedIndexAudit;
+exports.formatAuditReportHuman = formatAuditReportHuman;
+const mongoose_1 = __importDefault(require("mongoose"));
+exports.SYNC_CONFIRM_PHRASE = "DROP_EXTRA_INDEXES";
+exports.INDEX_QUERY_LOG_MODEL_NAME = "IndexQueryLog";
+const READ_QUERY_OPS = ["find", "findOne", "count", "countDocuments", "distinct"];
+const MONITOR_EXCLUDED_MODELS = new Set([exports.INDEX_QUERY_LOG_MODEL_NAME]);
+/** Set on queries run by the monitor itself so post hooks do not re-enter. */
+const INDEX_DIAG_INTERNAL_EXPLAIN = "_indexDiagExplain";
+let explainMonitorDepth = 0;
+/** Whether a completed query should trigger sampled explain monitoring. */
+function shouldMonitorQuery(query) {
+    if (explainMonitorDepth > 0)
+        return false;
+    const opts = query.options;
+    if (opts?.explain)
+        return false;
+    if (opts?.[INDEX_DIAG_INTERNAL_EXPLAIN])
+        return false;
+    return true;
+}
+function envBool(name, fallback = false) {
+    const v = process.env[name];
+    if (v === undefined)
+        return fallback;
+    return v === "1" || v.toLowerCase() === "true";
+}
+function envFloat(name, fallback) {
+    const n = parseFloat(process.env[name] ?? "");
+    return Number.isFinite(n) ? n : fallback;
+}
+function envInt(name, fallback) {
+    const n = parseInt(process.env[name] ?? "", 10);
+    return Number.isFinite(n) ? n : fallback;
+}
+function truncate(value, max = 120) {
+    const oneLine = value.replace(/[\r\n]+/g, " ").trim();
+    if (oneLine.length <= max)
+        return oneLine;
+    return `${oneLine.slice(0, max - 1)}…`;
+}
+function summarizeFilter(filter) {
+    if (filter === undefined || filter === null)
+        return "{}";
+    try {
+        return truncate(JSON.stringify(filter));
+    }
+    catch {
+        return "[unserializable]";
+    }
+}
+/** Stages that actually read from the collection (not plan wrappers like PROJECTION_*). */
+const DATA_ACCESS_STAGES = new Set([
+    "COLLSCAN",
+    "IXSCAN",
+    "FETCH",
+    "IDHACK",
+    "DISTINCT_SCAN",
+    "TEXT",
+    "COUNT_SCAN",
+    "COUNT",
+    "SUBPLAN",
+]);
+function isDataAccessStage(name) {
+    return DATA_ACCESS_STAGES.has(name);
+}
+function stageName(stage) {
+    if (!stage || typeof stage !== "object")
+        return undefined;
+    const s = stage;
+    if (typeof s.stage === "string")
+        return s.stage;
+    if (s.inputStage)
+        return stageName(s.inputStage);
+    if (Array.isArray(s.inputStages) && s.inputStages[0])
+        return stageName(s.inputStages[0]);
+    return undefined;
+}
+/** Deepest data-access stages from collection inward (e.g. IXSCAN → FETCH). */
+function extractScanStagePath(stage) {
+    if (!stage || typeof stage !== "object")
+        return [];
+    const s = stage;
+    const name = typeof s.stage === "string" ? s.stage : undefined;
+    const childPaths = [];
+    if (s.inputStage)
+        childPaths.push(extractScanStagePath(s.inputStage));
+    if (Array.isArray(s.inputStages)) {
+        for (const st of s.inputStages)
+            childPaths.push(extractScanStagePath(st));
+    }
+    if (s.shards && typeof s.shards === "object") {
+        for (const shard of Object.values(s.shards)) {
+            if (shard && typeof shard === "object") {
+                const es = shard.executionStages;
+                if (es)
+                    childPaths.push(extractScanStagePath(es));
+            }
+        }
+    }
+    const deepest = childPaths.reduce((best, cur) => (cur.length > best.length ? cur : best), []);
+    if (name && isDataAccessStage(name)) {
+        return [...deepest, name];
+    }
+    return deepest;
+}
+function formatScanStagePath(path) {
+    if (!path.length)
+        return undefined;
+    return path.join(" → ");
+}
+function scanStageFromExplain(rootStage) {
+    return formatScanStagePath(extractScanStagePath(rootStage)) ?? stageName(rootStage);
+}
+function hasCollScan(stage) {
+    if (!stage || typeof stage !== "object")
+        return false;
+    const s = stage;
+    if (s.stage === "COLLSCAN")
+        return true;
+    if (s.inputStage && hasCollScan(s.inputStage))
+        return true;
+    if (Array.isArray(s.inputStages)) {
+        return s.inputStages.some((st) => hasCollScan(st));
+    }
+    return false;
+}
+function getExecutionStats(explain) {
+    const stats = explain.executionStats;
+    if (stats && typeof stats === "object")
+        return stats;
+    return undefined;
+}
+function classifyExplain(explain, options = {}) {
+    const minDocsExamined = options.minDocsExamined ?? 50;
+    const docsExaminedRatio = options.docsExaminedRatio ?? 10;
+    const smallCollectionThreshold = options.smallCollectionThreshold ?? 1000;
+    if (options.collectionDocCount !== undefined &&
+        options.collectionDocCount < smallCollectionThreshold) {
+        return { severity: "ignore", reason: "small_collection" };
+    }
+    const stats = getExecutionStats(explain);
+    if (!stats) {
+        return { severity: "ignore", reason: "no_execution_stats" };
+    }
+    const nReturned = Number(stats.nReturned ?? 0);
+    const totalDocsExamined = Number(stats.totalDocsExamined ?? 0);
+    const totalKeysExamined = Number(stats.totalKeysExamined ?? 0);
+    const millis = Number(stats.executionTimeMillis ?? 0);
+    const rootStage = stats.executionStages ?? explain.queryPlanner;
+    const stage = scanStageFromExplain(rootStage);
+    const collScan = hasCollScan(rootStage);
+    if (collScan && totalDocsExamined >= minDocsExamined) {
+        const ratio = totalDocsExamined / Math.max(nReturned, 1);
+        if (ratio >= docsExaminedRatio) {
+            return {
+                severity: "alert",
+                reason: "collection_scan",
+                stage,
+                totalDocsExamined,
+                nReturned,
+                totalKeysExamined,
+                millis,
+            };
+        }
+    }
+    if (!collScan &&
+        totalKeysExamined > 0 &&
+        totalDocsExamined >= minDocsExamined &&
+        totalDocsExamined > nReturned * docsExaminedRatio) {
+        return {
+            severity: "warn",
+            reason: "inefficient_index",
+            stage,
+            totalDocsExamined,
+            nReturned,
+            totalKeysExamined,
+            millis,
+        };
+    }
+    if (collScan) {
+        return {
+            severity: "warn",
+            reason: "collection_scan_below_threshold",
+            stage,
+            totalDocsExamined,
+            nReturned,
+            totalKeysExamined,
+            millis,
+        };
+    }
+    return {
+        severity: "ok",
+        stage,
+        totalDocsExamined,
+        nReturned,
+        totalKeysExamined,
+        millis,
+    };
+}
+function formatSchemaIndex(entry) {
+    const [keys, options] = entry;
+    const out = { keys };
+    if (options && Object.keys(options).length)
+        out.options = options;
+    return out;
+}
+async function auditModel(model, opts) {
+    const modelName = model.modelName;
+    const collection = model.collection.name;
+    const entry = {
+        modelName,
+        collection,
+        ok: true,
+        missing: [],
+        extra: [],
+        schemaIndexes: [],
+        dbIndexes: [],
+    };
+    try {
+        const schemaIndexes = model.schema.indexes();
+        entry.schemaIndexes = schemaIndexes.map(formatSchemaIndex);
+        const dbIndexes = await model.listIndexes();
+        entry.dbIndexes = dbIndexes.map((idx) => ({
+            name: String(idx.name),
+            key: idx.key,
+            ...idx,
+        }));
+        const diff = await model.diffIndexes();
+        entry.missing = (diff.toCreate || []);
+        entry.extra = (diff.toDrop || []);
+        entry.ok = entry.missing.length === 0 && entry.extra.length === 0;
+        if (opts?.includeUnused) {
+            try {
+                const stats = (await model.collection
+                    .aggregate([{ $indexStats: {} }])
+                    .toArray());
+                entry.unused = stats
+                    .filter((s) => s.name !== "_id_" && (s.accesses?.ops ?? 0) === 0)
+                    .map((s) => ({ name: s.name, accesses: s.accesses?.ops ?? 0 }));
+            }
+            catch {
+                entry.unused = [];
+            }
+        }
+    }
+    catch (err) {
+        entry.ok = false;
+        entry.error = err instanceof Error ? err.message : String(err);
+    }
+    return entry;
+}
+async function auditAllModels(models, opts) {
+    const collections = [];
+    const names = Object.keys(models).sort();
+    for (const name of names) {
+        collections.push(await auditModel(models[name], opts));
+    }
+    const withMissing = collections.filter((c) => c.missing.length > 0).length;
+    const withExtra = collections.filter((c) => c.extra.length > 0).length;
+    const errors = collections.filter((c) => c.error).length;
+    return {
+        generatedAt: new Date().toISOString(),
+        collections,
+        summary: {
+            total: collections.length,
+            ok: collections.filter((c) => c.ok).length,
+            withMissing,
+            withExtra,
+            errors,
+        },
+    };
+}
+async function syncAllModels(models, opts) {
+    if (opts.confirm !== exports.SYNC_CONFIRM_PHRASE) {
+        throw new Error(`syncIndexes requires confirm="${exports.SYNC_CONFIRM_PHRASE}" (creates missing indexes and drops extras not in schema)`);
+    }
+    const results = [];
+    const names = Object.keys(models).sort();
+    for (const name of names) {
+        const model = models[name];
+        try {
+            const before = await model.diffIndexes();
+            await model.syncIndexes();
+            results.push({
+                modelName: name,
+                created: (before.toCreate || []).map((k) => JSON.stringify(k)),
+                dropped: before.toDrop || [],
+            });
+        }
+        catch (err) {
+            results.push({
+                modelName: name,
+                error: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    return results;
+}
+const builtin_models_1 = require("./builtin_models");
+/** Load app MODEL_DIR plus jxp built-in models (app overrides built-ins). */
+function loadModelsFromDir(modelDir) {
+    return (0, builtin_models_1.loadAllModels)(modelDir);
+}
+function wireQueryLogPersistence(models) {
+    const logModel = models.indexquerylog ||
+        Object.values(models).find((m) => m.modelName === exports.INDEX_QUERY_LOG_MODEL_NAME);
+    if (logModel) {
+        setQueryLogModel(logModel);
+    }
+    else {
+        setQueryLogModel(null);
+    }
+}
+function resolveIndexDiagnosticsConfig(config) {
+    const isProd = process.env.NODE_ENV === "production";
+    const masterOn = config?.enabled ?? envBool("INDEX_DIAGNOSTICS_ENABLED", false);
+    let monitorOn;
+    if (config?.query_monitor?.enabled !== undefined) {
+        monitorOn = config.query_monitor.enabled;
+    }
+    else if (process.env.QUERY_INDEX_MONITOR !== undefined) {
+        monitorOn = envBool("QUERY_INDEX_MONITOR");
+    }
+    else {
+        monitorOn = isProd ? masterOn : true;
+    }
+    const enabled = masterOn || monitorOn === true;
+    const queryDefaults = isProd
+        ? {
+            enabled: false,
+            sample_rate: 0.02,
+            min_docs_examined: 100,
+            docs_examined_ratio: 10,
+            small_collection_threshold: 1000,
+            buffer_size: 200,
+        }
+        : {
+            enabled: true,
+            sample_rate: 1.0,
+            min_docs_examined: 20,
+            docs_examined_ratio: 5,
+            small_collection_threshold: 500,
+            buffer_size: 200,
+        };
+    const qm = config?.query_monitor ?? {};
+    const query_monitor = {
+        enabled: enabled && monitorOn === true,
+        sample_rate: qm.sample_rate ?? envFloat("QUERY_INDEX_SAMPLE_RATE", queryDefaults.sample_rate),
+        min_docs_examined: qm.min_docs_examined ??
+            envInt("QUERY_INDEX_MIN_DOCS_EXAMINED", queryDefaults.min_docs_examined),
+        docs_examined_ratio: qm.docs_examined_ratio ??
+            envFloat("QUERY_INDEX_DOCS_EXAMINED_RATIO", queryDefaults.docs_examined_ratio),
+        small_collection_threshold: qm.small_collection_threshold ??
+            envInt("QUERY_INDEX_SMALL_COLLECTION_THRESHOLD", queryDefaults.small_collection_threshold),
+        buffer_size: qm.buffer_size ?? envInt("QUERY_INDEX_BUFFER_SIZE", queryDefaults.buffer_size),
+    };
+    return {
+        enabled,
+        query_monitor,
+    };
+}
+const queryBuffer = [];
+let resolvedConfig = null;
+let pluginRegistered = false;
+let queryLogModel = null;
+let persistQueries = true;
+function setQueryLogModel(model) {
+    queryLogModel = model;
+}
+function setPersistQueries(enabled) {
+    persistQueries = enabled;
+}
+function getQueryMonitorBuffer() {
+    return [...queryBuffer];
+}
+function envWantsQueryMonitor() {
+    if (envBool("INDEX_DIAGNOSTICS_ENABLED", false))
+        return true;
+    if (process.env.QUERY_INDEX_MONITOR !== undefined) {
+        return envBool("QUERY_INDEX_MONITOR");
+    }
+    return process.env.NODE_ENV !== "production";
+}
+function getQueryMonitorStatus() {
+    const isProd = process.env.NODE_ENV === "production";
+    const cfg = resolvedConfig;
+    const diagnostics_enabled = cfg?.enabled ?? false;
+    const query_monitor_enabled = cfg?.query_monitor?.enabled ?? false;
+    const active = diagnostics_enabled && query_monitor_enabled;
+    const registration_missing = cfg === null && envWantsQueryMonitor();
+    const envSnapshot = {
+        QUERY_INDEX_MONITOR: process.env.QUERY_INDEX_MONITOR,
+        INDEX_DIAGNOSTICS_ENABLED: process.env.INDEX_DIAGNOSTICS_ENABLED,
+        NODE_ENV: process.env.NODE_ENV,
+    };
+    if (active) {
+        return {
+            active: true,
+            is_production: isProd,
+            diagnostics_enabled,
+            query_monitor_enabled,
+            registration_missing: false,
+            env: envSnapshot,
+            env_hints: [],
+        };
+    }
+    const env_hints = isProd
+        ? [
+            {
+                name: "INDEX_DIAGNOSTICS_ENABLED",
+                value: "true",
+                comment: "Required in production",
+            },
+            { name: "QUERY_INDEX_MONITOR", value: "true" },
+            {
+                name: "QUERY_INDEX_SAMPLE_RATE",
+                value: "0.02",
+                comment: "1–5% recommended",
+            },
+        ]
+        : [{ name: "QUERY_INDEX_MONITOR", value: "true" }];
+    if (registration_missing) {
+        env_hints.unshift({
+            name: "(restart)",
+            value: "required",
+            comment: "Env is set but monitor was not registered at startup — restart after upgrading jxp",
+        });
+    }
+    return {
+        active: false,
+        is_production: isProd,
+        diagnostics_enabled,
+        query_monitor_enabled,
+        registration_missing,
+        env: envSnapshot,
+        env_hints,
+    };
+}
+async function listQueryLogs(opts = {}) {
+    const limit = Math.min(Math.max(opts.limit ?? 50, 1), 500);
+    const skip = Math.max(opts.skip ?? 0, 0);
+    const config = getQueryMonitorConfig();
+    const monitor_status = getQueryMonitorStatus();
+    if (!queryLogModel || !persistQueries) {
+        const entries = getQueryMonitorBuffer()
+            .filter((e) => {
+            if (opts.severity && e.severity !== opts.severity)
+                return false;
+            if (opts.model_name && e.model !== opts.model_name)
+                return false;
+            return true;
+        })
+            .slice(skip, skip + limit);
+        return { config, monitor_status, entries, persisted: false };
+    }
+    const filter = {};
+    if (opts.severity)
+        filter.severity = opts.severity;
+    if (opts.model_name)
+        filter.model_name = opts.model_name;
+    const [docs, total] = await Promise.all([
+        queryLogModel
+            .find(filter)
+            .sort({ observed_at: -1 })
+            .skip(skip)
+            .limit(limit)
+            .lean(),
+        queryLogModel.countDocuments(filter),
+    ]);
+    const entries = docs.map((doc) => {
+        const d = doc;
+        const observed = d.observed_at || d.createdAt;
+        return {
+            at: observed instanceof Date ? observed.toISOString() : String(observed ?? ""),
+            model: String(d.model_name ?? ""),
+            op: String(d.op ?? ""),
+            filterSummary: String(d.filter_summary ?? "{}"),
+            severity: d.severity,
+            reason: d.reason ? String(d.reason) : undefined,
+            stage: d.stage ? String(d.stage) : undefined,
+            totalDocsExamined: d.total_docs_examined,
+            nReturned: d.n_returned,
+            totalKeysExamined: d.total_keys_examined,
+            millis: d.millis,
+            id: d._id ? String(d._id) : undefined,
+        };
+    });
+    return { config, monitor_status, entries, persisted: true, total };
+}
+function getQueryMonitorConfig() {
+    return resolvedConfig?.query_monitor ?? null;
+}
+function shouldSample(cfg) {
+    if (!cfg.enabled || !cfg.query_monitor.enabled)
+        return false;
+    if (cfg.query_monitor.sample_rate >= 1)
+        return true;
+    return Math.random() < cfg.query_monitor.sample_rate;
+}
+function pushQueryEntry(entry, maxSize) {
+    queryBuffer.push(entry);
+    while (queryBuffer.length > maxSize) {
+        queryBuffer.shift();
+    }
+}
+async function persistQueryEntry(entry) {
+    if (!persistQueries || !queryLogModel)
+        return;
+    if (entry.severity !== "alert" && entry.severity !== "warn")
+        return;
+    try {
+        await queryLogModel.create({
+            model_name: entry.model,
+            op: entry.op,
+            filter_summary: entry.filterSummary,
+            severity: entry.severity,
+            reason: entry.reason,
+            stage: entry.stage,
+            total_docs_examined: entry.totalDocsExamined,
+            n_returned: entry.nReturned,
+            total_keys_examined: entry.totalKeysExamined,
+            millis: entry.millis,
+            observed_at: new Date(entry.at),
+        });
+    }
+    catch {
+        // persistence must not affect API requests
+    }
+}
+async function runExplainMonitor(query, op, cfg) {
+    if (!shouldMonitorQuery(query))
+        return;
+    const model = query.model;
+    if (!model)
+        return;
+    if (MONITOR_EXCLUDED_MODELS.has(model.modelName))
+        return;
+    const qm = cfg.query_monitor;
+    let collectionDocCount;
+    explainMonitorDepth += 1;
+    try {
+        try {
+            const estimated = await model.estimatedDocumentCount();
+            collectionDocCount = estimated;
+        }
+        catch {
+            collectionDocCount = undefined;
+        }
+        const explainQuery = query.clone().explain("executionStats");
+        explainQuery.setOptions({ [INDEX_DIAG_INTERNAL_EXPLAIN]: true });
+        const explain = (await explainQuery);
+        const classification = classifyExplain(explain, {
+            minDocsExamined: qm.min_docs_examined,
+            docsExaminedRatio: qm.docs_examined_ratio,
+            smallCollectionThreshold: qm.small_collection_threshold,
+            collectionDocCount,
+        });
+        if (classification.severity === "ignore" || classification.severity === "ok")
+            return;
+        const entry = {
+            at: new Date().toISOString(),
+            model: model.modelName,
+            op,
+            filterSummary: summarizeFilter(query.getFilter()),
+            severity: classification.severity,
+            reason: classification.reason,
+            stage: classification.stage,
+            totalDocsExamined: classification.totalDocsExamined,
+            nReturned: classification.nReturned,
+            totalKeysExamined: classification.totalKeysExamined,
+            millis: classification.millis,
+        };
+        pushQueryEntry(entry, qm.buffer_size);
+        void persistQueryEntry(entry);
+    }
+    catch {
+        // explain failures must not affect API requests
+    }
+    finally {
+        explainMonitorDepth -= 1;
+    }
+}
+function attachQueryMonitorHooks(schema, cfg) {
+    for (const op of READ_QUERY_OPS) {
+        schema.post(op, function () {
+            if (!shouldSample(cfg))
+                return;
+            const query = this;
+            if (!shouldMonitorQuery(query))
+                return;
+            setImmediate(() => {
+                void runExplainMonitor(query, op, cfg);
+            });
+        });
+    }
+}
+/**
+ * Register mongoose plugin for sampled explain-based query monitoring.
+ * Call before models are loaded.
+ */
+function registerQueryIndexMonitor(config) {
+    resolvedConfig = resolveIndexDiagnosticsConfig(config);
+    if (!resolvedConfig.enabled || !resolvedConfig.query_monitor.enabled)
+        return;
+    if (pluginRegistered)
+        return;
+    pluginRegistered = true;
+    const cfg = resolvedConfig;
+    mongoose_1.default.plugin((schema) => {
+        attachQueryMonitorHooks(schema, cfg);
+    });
+}
+let auditCache = null;
+const AUDIT_CACHE_MS = 30_000;
+async function getCachedIndexAudit(models, opts) {
+    const now = Date.now();
+    if (!opts?.refresh && auditCache && now - auditCache.at < AUDIT_CACHE_MS) {
+        return auditCache.report;
+    }
+    const report = await auditAllModels(models, opts);
+    auditCache = { at: now, report };
+    return report;
+}
+function formatAuditReportHuman(report) {
+    const lines = [];
+    for (const c of report.collections) {
+        if (c.error) {
+            lines.push(`${c.modelName}: ERROR ${c.error}`);
+            continue;
+        }
+        if (c.ok) {
+            lines.push(`${c.modelName}: OK`);
+            continue;
+        }
+        const parts = [`${c.modelName}:`];
+        if (c.missing.length)
+            parts.push(`MISSING ${c.missing.map((k) => JSON.stringify(k)).join(", ")}`);
+        if (c.extra.length)
+            parts.push(`EXTRA [${c.extra.join(", ")}]`);
+        lines.push(parts.join(" "));
+    }
+    lines.push(`--- summary: ${report.summary.ok}/${report.summary.total} OK, ${report.summary.withMissing} missing, ${report.summary.withExtra} extra, ${report.summary.errors} errors`);
+    return lines.join("\n");
+}
+//# sourceMappingURL=index_diagnostics.js.map