taurusdb-core 0.1.0

package/dist/engine/data-access/storage.js

@@ -0,0 +1,96 @@
+import { clampInteger, escapeLikePrefix, parseStatementDigestRows, parseTableStorageRows, quoteLiteral, } from "../helpers.js";
+export async function findStorageStatementDigests(engine, input, ctx) {
+    const maxRows = Math.min(clampInteger(input.maxCandidates, 5, 1, 10) * 2, 20);
+    const whereClauses = ["DIGEST_TEXT IS NOT NULL", "DIGEST_TEXT <> 'NULL'"];
+    const focusedTable = input.table?.includes(".")
+        ? input.table.split(".").slice(1).join(".")
+        : input.table;
+    if (ctx.database) {
+        whereClauses.push(`SCHEMA_NAME = ${quoteLiteral(ctx.database)}`);
+    }
+    if (focusedTable) {
+        const tableLike = quoteLiteral(`%${escapeLikePrefix(focusedTable)}%`);
+        whereClauses.push(`(DIGEST_TEXT LIKE ${tableLike} ESCAPE '\\\\' OR QUERY_SAMPLE_TEXT LIKE ${tableLike} ESCAPE '\\\\')`);
+    }
+    const sql = `
+      SELECT
+        SCHEMA_NAME AS schema_name,
+        DIGEST AS digest,
+        DIGEST_TEXT AS digest_text,
+        QUERY_SAMPLE_TEXT AS query_sample_text,
+        COUNT_STAR AS exec_count,
+        ROUND(AVG_TIMER_WAIT / 1000000000, 3) AS avg_latency_ms,
+        ROUND(SUM_TIMER_WAIT / 1000000000, 3) AS total_latency_ms,
+        ROUND(MAX_TIMER_WAIT / 1000000000, 3) AS max_latency_ms,
+        ROUND(SUM_LOCK_TIME / 1000000000 / NULLIF(COUNT_STAR, 0), 3) AS avg_lock_time_ms,
+        ROUND(SUM_ROWS_EXAMINED / NULLIF(COUNT_STAR, 0), 3) AS avg_rows_examined,
+        ROUND(SUM_SORT_ROWS / NULLIF(COUNT_STAR, 0), 3) AS avg_sort_rows,
+        ROUND(SUM_CREATED_TMP_TABLES / NULLIF(COUNT_STAR, 0), 3) AS avg_tmp_tables,
+        ROUND(SUM_CREATED_TMP_DISK_TABLES / NULLIF(COUNT_STAR, 0), 3) AS avg_tmp_disk_tables,
+        SUM_SELECT_SCAN AS select_scan_count,
+        SUM_NO_INDEX_USED AS no_index_used_count
+      FROM performance_schema.events_statements_summary_by_digest
+      WHERE ${whereClauses.join(" AND ")}
+      ORDER BY
+        SUM_CREATED_TMP_DISK_TABLES DESC,
+        SUM_ROWS_EXAMINED DESC,
+        SUM_SORT_ROWS DESC,
+        SUM_TIMER_WAIT DESC,
+        COUNT_STAR DESC
+      LIMIT ${maxRows}
+    `.trim();
+    const result = await engine.executor.executeReadonly(sql, ctx, {
+        maxRows,
+        maxColumns: 15,
+        maxFieldChars: 4096,
+        timeoutMs: ctx.limits.timeoutMs,
+    });
+    return parseStatementDigestRows(result);
+}
+export async function findTableStorageStats(engine, input, ctx) {
+    const maxRows = clampInteger(input.maxCandidates, 5, 1, 10);
+    const whereClauses = [
+        "TABLE_TYPE = 'BASE TABLE'",
+        "TABLE_SCHEMA NOT IN ('mysql', 'information_schema', 'performance_schema', 'sys')",
+    ];
+    const focusedTable = input.table?.includes(".")
+        ? {
+            schema: input.table.split(".")[0],
+            table: input.table.split(".").slice(1).join("."),
+        }
+        : {
+            schema: ctx.database,
+            table: input.table,
+        };
+    if (focusedTable.schema) {
+        whereClauses.push(`TABLE_SCHEMA = ${quoteLiteral(focusedTable.schema)}`);
+    }
+    else if (ctx.database && input.scope !== "instance") {
+        whereClauses.push(`TABLE_SCHEMA = ${quoteLiteral(ctx.database)}`);
+    }
+    if (focusedTable.table) {
+        whereClauses.push(`TABLE_NAME = ${quoteLiteral(focusedTable.table)}`);
+    }
+    const sql = `
+      SELECT
+        TABLE_SCHEMA AS schema_name,
+        TABLE_NAME AS table_name,
+        ENGINE AS engine,
+        TABLE_ROWS AS row_count_estimate,
+        ROUND((DATA_LENGTH + INDEX_LENGTH) / 1024 / 1024, 3) AS total_mb,
+        ROUND(DATA_LENGTH / 1024 / 1024, 3) AS data_mb,
+        ROUND(INDEX_LENGTH / 1024 / 1024, 3) AS index_mb,
+        ROUND(DATA_FREE / 1024 / 1024, 3) AS data_free_mb
+      FROM information_schema.TABLES
+      WHERE ${whereClauses.join(" AND ")}
+      ORDER BY (DATA_LENGTH + INDEX_LENGTH) DESC, TABLE_ROWS DESC, TABLE_SCHEMA ASC, TABLE_NAME ASC
+      LIMIT ${maxRows}
+    `.trim();
+    const result = await engine.executor.executeReadonly(sql, ctx, {
+        maxRows,
+        maxColumns: 8,
+        maxFieldChars: 512,
+        timeoutMs: ctx.limits.timeoutMs,
+    });
+    return parseTableStorageRows(result);
+}

package/dist/engine/data-access.d.ts

@@ -0,0 +1,4 @@
+export { showProcesslist } from "./data-access/processlist.js";
+export { showLockWaits, findMetadataLockWaits, findLatestDeadlock } from "./data-access/locks.js";
+export { findStatementDigestSample, findStatementDigestSampleForSql, findStatementDigestCandidatesForSqlHints, findTopStatementDigests, isPerformanceSchemaEnabled, findStatementWaitEvents, } from "./data-access/statements.js";
+export { findStorageStatementDigests, findTableStorageStats } from "./data-access/storage.js";

package/dist/engine/data-access.js

@@ -0,0 +1,4 @@
+export { showProcesslist } from "./data-access/processlist.js";
+export { showLockWaits, findMetadataLockWaits, findLatestDeadlock } from "./data-access/locks.js";
+export { findStatementDigestSample, findStatementDigestSampleForSql, findStatementDigestCandidatesForSqlHints, findTopStatementDigests, isPerformanceSchemaEnabled, findStatementWaitEvents, } from "./data-access/statements.js";
+export { findStorageStatementDigests, findTableStorageStats } from "./data-access/storage.js";

package/dist/engine/diagnostics.d.ts

@@ -0,0 +1,7 @@
+export { diagnoseSlowQuery } from "./workflows/slow-query.js";
+export { diagnoseServiceLatency } from "./workflows/service-latency.js";
+export { diagnoseDbHotspot } from "./workflows/db-hotspot.js";
+export { findTopSlowSql } from "./workflows/top-slow-sql.js";
+export { diagnoseConnectionSpike } from "./workflows/connection-spike.js";
+export { diagnoseLockContention } from "./workflows/lock-contention.js";
+export { diagnoseStoragePressure } from "./workflows/storage-pressure.js";

package/dist/engine/diagnostics.js

@@ -0,0 +1,7 @@
+export { diagnoseSlowQuery } from "./workflows/slow-query.js";
+export { diagnoseServiceLatency } from "./workflows/service-latency.js";
+export { diagnoseDbHotspot } from "./workflows/db-hotspot.js";
+export { findTopSlowSql } from "./workflows/top-slow-sql.js";
+export { diagnoseConnectionSpike } from "./workflows/connection-spike.js";
+export { diagnoseLockContention } from "./workflows/lock-contention.js";
+export { diagnoseStoragePressure } from "./workflows/storage-pressure.js";

package/dist/engine/helper-modules/diagnostics.d.ts

@@ -0,0 +1,57 @@
+import type { SessionContext } from "../../context/session-context.js";
+import type { MetricAlias, MetricSummary, MetricsSource } from "../../diagnostics/metrics-source.js";
+import type { DbHotspotItem, DiagnosticBaseInput, DiagnosticNextToolInput, DiagnosticRootCauseCandidate, DiagnosticSeverity, DiagnoseConnectionSpikeInput, DiagnoseLockContentionInput, ServiceLatencyCandidate, ServiceLatencySuspectedCategory } from "../../diagnostics/types.js";
+import type { ExplainResult } from "../../executor/sql-executor.js";
+export declare function countBy<T>(rows: T[], pick: (row: T) => string | undefined): Array<{
+    key: string;
+    count: number;
+}>;
+export declare function pickMetric(metrics: MetricSummary[], alias: MetricAlias): MetricSummary | undefined;
+export declare function metricSummaryText(metric: MetricSummary): string;
+export declare function roundMetric(value: number): number;
+export interface SafeMetricsQueryResult {
+    metrics: MetricSummary[];
+    error?: string;
+}
+export declare function queryMetricsSafely(source: MetricsSource | undefined, aliases: MetricAlias[], input: DiagnosticBaseInput, ctx: SessionContext): Promise<MetricSummary[]>;
+export declare function queryMetricsWithStatus(source: MetricsSource | undefined, aliases: MetricAlias[], input: DiagnosticBaseInput, ctx: SessionContext): Promise<SafeMetricsQueryResult>;
+export declare function metricsSourceLimitation(source: MetricsSource | undefined): string[];
+export declare function confidenceWeight(value: ServiceLatencyCandidate["confidence"]): number;
+export declare function rootCauseBasePriority(code: string): number;
+export declare function rootCauseConfidenceWeight(value: DiagnosticRootCauseCandidate["confidence"]): number;
+export declare function rootCauseRankScore(candidate: DiagnosticRootCauseCandidate): number;
+export declare function sortRootCauseCandidates(candidates: DiagnosticRootCauseCandidate[]): DiagnosticRootCauseCandidate[];
+export declare function severityFromSlowQueryEvidence(riskSummary: ExplainResult["riskSummary"], candidates: DiagnosticRootCauseCandidate[]): DiagnosticSeverity;
+export declare function serviceCategoryPriority(value: ServiceLatencySuspectedCategory): number;
+export declare function hotspotTypePriority(value: DbHotspotItem["type"]): number;
+export declare function buildSlowQueryNextToolInput(source: {
+    sqlHash?: string;
+    digestText?: string;
+    sampleSql?: string;
+}, input: DiagnosticBaseInput, rationale: string): DiagnosticNextToolInput | undefined;
+export declare function buildBaseNextToolInput(input: DiagnosticBaseInput): Record<string, unknown>;
+export declare function buildDbHotspotNextToolInput(source: {
+    scope?: "sql" | "table" | "session";
+}, input: DiagnosticBaseInput, rationale: string): DiagnosticNextToolInput;
+export declare function buildFindTopSlowSqlNextToolInput(source: {
+    sortBy?: "avg_latency" | "total_latency" | "exec_count" | "lock_time";
+    topN?: number;
+}, input: DiagnosticBaseInput, rationale: string): DiagnosticNextToolInput;
+export declare function buildLockContentionNextToolInput(source: {
+    table?: string;
+    blockerSessionId?: string;
+}, input: DiagnosticBaseInput, rationale: string): DiagnosticNextToolInput;
+export declare function buildConnectionSpikeNextToolInput(source: {
+    user?: string;
+    clientHost?: string;
+}, input: DiagnosticBaseInput, rationale: string): DiagnosticNextToolInput;
+export declare function buildShowProcesslistNextToolInput(source: {
+    user?: string;
+    host?: string;
+    command?: string;
+    includeIdle?: boolean;
+    includeInfo?: boolean;
+}, input: DiagnosticBaseInput, rationale: string): DiagnosticNextToolInput;
+export declare function dedupeNextToolInputs(inputs: DiagnosticNextToolInput[]): DiagnosticNextToolInput[];
+export declare function evidenceRowLimit(level: DiagnoseConnectionSpikeInput["evidenceLevel"]): number;
+export declare function lockEvidenceRowLimit(level: DiagnoseLockContentionInput["evidenceLevel"]): number;

package/dist/engine/helper-modules/diagnostics.js

@@ -0,0 +1,322 @@
+export function countBy(rows, pick) {
+    const counts = new Map();
+    for (const row of rows) {
+        const key = pick(row);
+        if (!key) {
+            continue;
+        }
+        counts.set(key, (counts.get(key) ?? 0) + 1);
+    }
+    return [...counts.entries()]
+        .map(([key, count]) => ({ key, count }))
+        .sort((left, right) => right.count - left.count || left.key.localeCompare(right.key));
+}
+export function pickMetric(metrics, alias) {
+    return metrics.find((metric) => metric.alias === alias);
+}
+export function metricSummaryText(metric) {
+    const parts = [
+        `metric=${metric.metricName}`,
+        `points=${metric.points.length}`,
+        metric.latest !== undefined
+            ? `latest=${roundMetric(metric.latest)}`
+            : undefined,
+        metric.max !== undefined ? `max=${roundMetric(metric.max)}` : undefined,
+        metric.avg !== undefined ? `avg=${roundMetric(metric.avg)}` : undefined,
+    ].filter((part) => part !== undefined);
+    return parts.join(", ");
+}
+export function roundMetric(value) {
+    return Math.round(value * 1000) / 1000;
+}
+export async function queryMetricsSafely(source, aliases, input, ctx) {
+    const result = await queryMetricsWithStatus(source, aliases, input, ctx);
+    return result.metrics;
+}
+export async function queryMetricsWithStatus(source, aliases, input, ctx) {
+    if (!source) {
+        return { metrics: [] };
+    }
+    try {
+        return {
+            metrics: await source.query({ aliases, timeRange: input.timeRange }, ctx),
+        };
+    }
+    catch (error) {
+        return {
+            metrics: [],
+            error: error instanceof Error && error.message.trim().length > 0
+                ? error.message
+                : "Metrics query failed.",
+        };
+    }
+}
+export function metricsSourceLimitation(source) {
+    return source
+        ? []
+        : ["No CES or control-plane metrics source is configured yet."];
+}
+export function confidenceWeight(value) {
+    switch (value) {
+        case "high":
+            return 3;
+        case "medium":
+            return 2;
+        default:
+            return 1;
+    }
+}
+export function rootCauseBasePriority(code) {
+    switch (code) {
+        case "slow_query_full_table_scan":
+            return 90;
+        case "slow_query_poor_index_usage":
+            return 60;
+        case "slow_query_runtime_scan_pressure":
+            return 70;
+        case "slow_query_tmp_disk_spill":
+            return 65;
+        case "slow_query_wait_event_lock_contention":
+            return 60;
+        case "slow_query_lock_wait_pressure":
+            return 55;
+        case "slow_query_filesort":
+            return 50;
+        case "slow_query_temp_structure":
+            return 45;
+        case "slow_query_wait_event_io_pressure":
+            return 40;
+        case "slow_query_wait_event_sync_contention":
+            return 35;
+        case "slow_query_taurus_feature_gap":
+            return 20;
+        case "slow_query_plan_collected":
+            return 10;
+        default:
+            return 0;
+    }
+}
+export function rootCauseConfidenceWeight(value) {
+    switch (value) {
+        case "high":
+            return 30;
+        case "medium":
+            return 15;
+        default:
+            return 0;
+    }
+}
+export function rootCauseRankScore(candidate) {
+    return (rootCauseBasePriority(candidate.code) +
+        rootCauseConfidenceWeight(candidate.confidence));
+}
+export function sortRootCauseCandidates(candidates) {
+    return [...candidates].sort((left, right) => rootCauseRankScore(right) - rootCauseRankScore(left) ||
+        rootCauseBasePriority(right.code) - rootCauseBasePriority(left.code) ||
+        rootCauseConfidenceWeight(right.confidence) -
+            rootCauseConfidenceWeight(left.confidence) ||
+        left.code.localeCompare(right.code));
+}
+export function severityFromSlowQueryEvidence(riskSummary, candidates) {
+    if (riskSummary.fullTableScanLikely ||
+        riskSummary.usesFilesort ||
+        riskSummary.usesTempStructure) {
+        return (riskSummary.estimatedRows ?? 0) >= 100_000 ? "high" : "warning";
+    }
+    if (candidates.some((candidate) => candidate.confidence === "high")) {
+        return "warning";
+    }
+    if (candidates.some((candidate) => candidate.confidence === "medium")) {
+        return "warning";
+    }
+    return "info";
+}
+export function serviceCategoryPriority(value) {
+    switch (value) {
+        case "lock_contention":
+            return 5;
+        case "connection_spike":
+            return 4;
+        case "slow_sql":
+            return 3;
+        case "resource_pressure":
+            return 2;
+        case "mixed":
+        default:
+            return 1;
+    }
+}
+export function hotspotTypePriority(value) {
+    switch (value) {
+        case "session":
+            return 3;
+        case "table":
+            return 2;
+        case "sql":
+        default:
+            return 1;
+    }
+}
+export function buildSlowQueryNextToolInput(source, input, rationale) {
+    const slowQueryInput = {};
+    if (input.datasource) {
+        slowQueryInput.datasource = input.datasource;
+    }
+    if (input.database) {
+        slowQueryInput.database = input.database;
+    }
+    if (input.timeRange) {
+        slowQueryInput.time_range = input.timeRange;
+    }
+    if (input.evidenceLevel) {
+        slowQueryInput.evidence_level = input.evidenceLevel;
+    }
+    if (input.includeRawEvidence !== undefined) {
+        slowQueryInput.include_raw_evidence = input.includeRawEvidence;
+    }
+    if (input.maxCandidates !== undefined) {
+        slowQueryInput.max_candidates = input.maxCandidates;
+    }
+    if (source.sampleSql) {
+        slowQueryInput.sql = source.sampleSql;
+    }
+    else if (source.digestText) {
+        slowQueryInput.digest_text = source.digestText;
+    }
+    else if (source.sqlHash) {
+        slowQueryInput.sql_hash = source.sqlHash;
+    }
+    else {
+        return undefined;
+    }
+    return {
+        tool: "diagnose_slow_query",
+        input: slowQueryInput,
+        rationale,
+    };
+}
+export function buildBaseNextToolInput(input) {
+    const nextInput = {};
+    if (input.datasource) {
+        nextInput.datasource = input.datasource;
+    }
+    if (input.database) {
+        nextInput.database = input.database;
+    }
+    if (input.timeRange) {
+        nextInput.time_range = input.timeRange;
+    }
+    if (input.evidenceLevel) {
+        nextInput.evidence_level = input.evidenceLevel;
+    }
+    if (input.includeRawEvidence !== undefined) {
+        nextInput.include_raw_evidence = input.includeRawEvidence;
+    }
+    if (input.maxCandidates !== undefined) {
+        nextInput.max_candidates = input.maxCandidates;
+    }
+    return nextInput;
+}
+export function buildDbHotspotNextToolInput(source, input, rationale) {
+    const nextInput = buildBaseNextToolInput(input);
+    if (source.scope) {
+        nextInput.scope = source.scope;
+    }
+    return {
+        tool: "diagnose_db_hotspot",
+        input: nextInput,
+        rationale,
+    };
+}
+export function buildFindTopSlowSqlNextToolInput(source, input, rationale) {
+    const nextInput = buildBaseNextToolInput(input);
+    if (source.sortBy) {
+        nextInput.sort_by = source.sortBy;
+    }
+    if (source.topN !== undefined) {
+        nextInput.top_n = source.topN;
+    }
+    return {
+        tool: "find_top_slow_sql",
+        input: nextInput,
+        rationale,
+    };
+}
+export function buildLockContentionNextToolInput(source, input, rationale) {
+    const nextInput = buildBaseNextToolInput(input);
+    if (source.table) {
+        nextInput.table = source.table;
+    }
+    if (source.blockerSessionId) {
+        nextInput.blocker_session_id = source.blockerSessionId;
+    }
+    return {
+        tool: "diagnose_lock_contention",
+        input: nextInput,
+        rationale,
+    };
+}
+export function buildConnectionSpikeNextToolInput(source, input, rationale) {
+    const nextInput = buildBaseNextToolInput(input);
+    if (source.user) {
+        nextInput.user = source.user;
+    }
+    if (source.clientHost) {
+        nextInput.client_host = source.clientHost;
+    }
+    nextInput.compare_baseline = false;
+    return {
+        tool: "diagnose_connection_spike",
+        input: nextInput,
+        rationale,
+    };
+}
+export function buildShowProcesslistNextToolInput(source, input, rationale) {
+    const nextInput = buildBaseNextToolInput(input);
+    if (source.user) {
+        nextInput.user = source.user;
+    }
+    if (source.host) {
+        nextInput.host = source.host;
+    }
+    if (source.command) {
+        nextInput.command = source.command;
+    }
+    nextInput.include_idle = source.includeIdle ?? true;
+    nextInput.include_info = source.includeInfo ?? true;
+    nextInput.max_rows = 20;
+    return {
+        tool: "show_processlist",
+        input: nextInput,
+        rationale,
+    };
+}
+export function dedupeNextToolInputs(inputs) {
+    return inputs.filter((item, index, allItems) => {
+        const key = `${item.tool}:${JSON.stringify(item.input)}`;
+        return (allItems.findIndex((candidate) => {
+            const candidateKey = `${candidate.tool}:${JSON.stringify(candidate.input)}`;
+            return candidateKey === key;
+        }) === index);
+    });
+}
+export function evidenceRowLimit(level) {
+    switch (level) {
+        case "full":
+            return 100;
+        case "standard":
+            return 50;
+        default:
+            return 20;
+    }
+}
+export function lockEvidenceRowLimit(level) {
+    switch (level) {
+        case "full":
+            return 100;
+        case "standard":
+            return 50;
+        default:
+            return 20;
+    }
+}

package/dist/engine/helper-modules/parsers.d.ts

@@ -0,0 +1,13 @@
+import type { QueryResult } from "../../executor/sql-executor.js";
+import type { DeadlockSummary, LockWaitRow, MetadataLockRow, ProcesslistRow, ReplicationStatusRow, StatementDigestRow, StatementWaitEventRow, TableStorageRow } from "./types.js";
+export declare function parseProcesslistRows(result: QueryResult): ProcesslistRow[];
+export declare function parseOptionalInteger(value: unknown): number | undefined;
+export declare function parseLockWaitRows(result: QueryResult): LockWaitRow[];
+export declare function isIdleTransactionBlocker(row: LockWaitRow): boolean;
+export declare function parseOptionalNumber(value: unknown): number | undefined;
+export declare function parseMetadataLockRows(result: QueryResult): MetadataLockRow[];
+export declare function parseDeadlockSummary(result: QueryResult): DeadlockSummary | undefined;
+export declare function parseStatementDigestRows(result: QueryResult): StatementDigestRow[];
+export declare function parseStatementWaitEventRows(result: QueryResult): StatementWaitEventRow[];
+export declare function parseTableStorageRows(result: QueryResult): TableStorageRow[];
+export declare function parseReplicationStatusRows(result: QueryResult): ReplicationStatusRow[];