forge-sql-orm 2.1.10 → 2.1.12

package/src/webtriggers/slowQuerySchedulerTrigger.ts

@@ -0,0 +1,89 @@
+import { getHttpResponse, TriggerResponse } from "./index";
+import { slowQueryPerHours } from "../utils/sqlUtils";
+import { ForgeSqlOperation } from "../core/ForgeSQLQueryBuilder";
+
+/**
+ * Scheduler trigger for analyzing slow queries from the last specified number of hours.
+ *
+ * This trigger analyzes slow queries from TiDB's slow query log system table and provides
+ * detailed performance information including SQL query text, memory usage, execution time,
+ * and execution plans. It's designed to be used as a scheduled trigger in Atlassian Forge
+ * to monitor query performance over time.
+ *
+ * The function queries the slow query system table to find queries executed within the
+ * specified time window and logs detailed performance information to the console. Results
+ * are limited to the top 50 slow queries to prevent excessive output.
+ *
+ * @param forgeSQLORM - The ForgeSQL operation instance for database access
+ * @param options - Configuration options for the slow query analysis
+ * @param options.hours - Number of hours to look back for slow queries (default: 1)
+ * @param options.timeout - Timeout in milliseconds for the query execution (default: 2000ms)
+ *
+ * @returns Promise<TriggerResponse<string>> - HTTP response with JSON stringified query results or error message
+ *
+ * @example
+ * ```typescript
+ * import ForgeSQL, { slowQuerySchedulerTrigger } from "forge-sql-orm";
+ *
+ * const forgeSQL = new ForgeSQL();
+ *
+ * // Basic usage with default options (1 hour, 2000ms timeout)
+ * export const slowQueryTrigger = () =>
+ *   slowQuerySchedulerTrigger(forgeSQL, { hours: 1, timeout: 2000 });
+ *
+ * // Analyze slow queries from the last 6 hours with extended timeout
+ * export const sixHourSlowQueryTrigger = () =>
+ *   slowQuerySchedulerTrigger(forgeSQL, { hours: 6, timeout: 5000 });
+ *
+ * // Analyze slow queries from the last 24 hours
+ * export const dailySlowQueryTrigger = () =>
+ *   slowQuerySchedulerTrigger(forgeSQL, { hours: 24, timeout: 3000 });
+ * ```
+ *
+ * @example
+ * ```yaml
+ * # manifest.yml configuration
+ * scheduledTrigger:
+ *   - key: slow-query-trigger
+ *     function: slowQueryTrigger
+ *     interval: hour
+ *
+ * function:
+ *   - key: slowQueryTrigger
+ *     handler: index.slowQueryTrigger
+ * ```
+ *
+ * @remarks
+ * - Results are automatically logged to the Forge Developer Console via `console.warn()`
+ * - The function returns up to 50 slow queries to prevent excessive logging
+ * - Transient timeouts are usually fine; repeated timeouts indicate the diagnostic query itself is slow
+ * - This trigger is best used with hourly intervals to catch slow queries in a timely manner
+ * - Error responses return HTTP 500 with error details
+ *
+ * @see {@link slowQueryPerHours} - The underlying function that performs the actual query analysis
+ */
+export async function slowQuerySchedulerTrigger(
+  forgeSQLORM: ForgeSqlOperation,
+  options: {
+    hours: number;
+    timeout: number;
+  },
+): Promise<TriggerResponse<string>> {
+  try {
+    return getHttpResponse<string>(
+      200,
+      JSON.stringify(
+        await slowQueryPerHours(forgeSQLORM, options?.hours ?? 1, options?.timeout ?? 3000),
+      ),
+    );
+  } catch (error: any) {
+    const errorMessage =
+      error?.debug?.sqlMessage ??
+      error?.debug?.message ??
+      error.message ??
+      "Unknown error occurred";
+    // eslint-disable-next-line no-console
+    console.error(errorMessage);
+    return getHttpResponse<string>(500, errorMessage);
+  }
+}

package/dist/webtriggers/topSlowestStatementLastHourTrigger.d.ts

@@ -1,114 +0,0 @@
-import { ForgeSqlOperation } from "../core/ForgeSQLQueryBuilder";
-import { OperationType } from "../utils/requestTypeContextUtils";
-interface TriggerOptions {
-    warnThresholdMs?: number;
-    memoryThresholdBytes?: number;
-    showPlan?: boolean;
-    operationType?: OperationType;
-    topN?: number;
-    hours?: number;
-    tables?: "SUMMARY_AND_HISTORY" | "CLUSTER_SUMMARY_AND_HISTORY";
-}
-interface TriggerResponse {
-    headers: {
-        "Content-Type": string[];
-    };
-    statusCode: number;
-    statusText?: string;
-    body: string;
-}
-/**
- * Performance monitoring scheduler trigger for Atlassian Forge SQL.
- *
- * This trigger analyzes query performance from the last hour and identifies slow or memory-intensive queries
- * that exceed configurable thresholds. It's designed specifically for Atlassian Forge's 16 MiB memory limit
- * and provides detailed insights for query optimization.
- *
- * ## Key Features
- * - **Memory-focused monitoring**: Primary focus on memory usage with configurable thresholds
- * - **Atlassian 16 MiB limit awareness**: Designed specifically for Forge SQL's memory constraints
- * - **Execution plan analysis**: Shows detailed query plans to help optimize memory consumption
- * - **Configurable thresholds**: Set custom memory usage and latency thresholds
- * - **Automatic filtering**: Excludes system queries (`Use`, `Set`, `Show`) and empty queries
- * - **Scheduled monitoring**: Run automatically on configurable intervals
- *
- * ## OR Logic Thresholds
- * Statements are included if they exceed **EITHER** threshold:
- * - `avgLatencyMs > warnThresholdMs` **OR**
- * - `avgMemBytes > memoryThresholdBytes`
- *
- * ## Configuration Tips
- * - **Memory-only monitoring**: Set `warnThresholdMs` to 10000ms (effectively disabled)
- * - **Latency-only monitoring**: Set `memoryThresholdBytes` to 16MB (16 * 1024 * 1024) (effectively disabled)
- * - **Combined monitoring**: Use both thresholds for comprehensive monitoring
- * - **Conservative monitoring**: 4MB warning (25% of 16MB limit)
- * - **Default monitoring**: 8MB warning (50% of 16MB limit)
- * - **Aggressive monitoring**: 12MB warning (75% of 16MB limit)
- *
- * ## Exclusions
- * - Statements with empty `digestText` or `digest`
- * - Service statements (`Use`, `Set`, `Show`)
- * - Queries that don't exceed either threshold
- *
- * @param orm - ForgeSQL ORM instance (required)
- * @param options - Configuration options
- * @param options.warnThresholdMs - Milliseconds threshold for latency monitoring (default: 300ms)
- * @param options.memoryThresholdBytes - Bytes threshold for memory usage monitoring (default: 8MB)
- * @param options.showPlan - Whether to include execution plan in logs (default: false)
- * @param options.operationType - Operation type context for query execution (default: "DML")
- * @param options.topN - Number of top slow queries to return (default: 1)
- * @param options.hours - Number of hours to look back (default: 1)
- * @param options.tables - Table configuration to use (default: "CLUSTER_SUMMARY_AND_HISTORY")
- * @returns Promise<TriggerResponse> - HTTP response with query results or error
- *
- * @example
- * ```typescript
- * import ForgeSQL, { topSlowestStatementLastHourTrigger } from "forge-sql-orm";
- *
- * const forgeSQL = new ForgeSQL();
- *
- * // Default thresholds: 300ms latency OR 8MB memory
- * export const performanceTrigger = () =>
- *   topSlowestStatementLastHourTrigger(forgeSQL);
- *
- * // Conservative memory monitoring: 4MB threshold
- * export const conservativeTrigger = () =>
- *   topSlowestStatementLastHourTrigger(forgeSQL, {
- *     memoryThresholdBytes: 4 * 1024 * 1024
- *   });
- *
- * // Memory-only monitoring: 4MB threshold (latency effectively disabled)
- * export const memoryOnlyTrigger = () =>
- *   topSlowestStatementLastHourTrigger(forgeSQL, {
- *     warnThresholdMs: 10000,
- *     memoryThresholdBytes: 4 * 1024 * 1024
- *   });
- *
- * // With execution plan in logs
- * export const withPlanTrigger = () =>
- *   topSlowestStatementLastHourTrigger(forgeSQL, { showPlan: true });
- * ```
- *
- * @example
- * ```yaml
- * # manifest.yml configuration
- * scheduledTrigger:
- *   - key: performance-trigger
- *     function: performanceTrigger
- *     interval: hour
- *
- * function:
- *   - key: performanceTrigger
- *     handler: index.performanceTrigger
- * ```
- */
-/**
- * Main scheduler trigger function to log the single slowest SQL statement from the last hour.
- *
- * @param orm - ForgeSQL ORM instance (required)
- * @param options - Configuration options
- * @returns Promise<TriggerResponse> - HTTP response with query results or error
- */
-export declare const topSlowestStatementLastHourTrigger: (orm: ForgeSqlOperation, options?: TriggerOptions) => Promise<TriggerResponse>;
-export {};
-//# sourceMappingURL=topSlowestStatementLastHourTrigger.d.ts.map

package/dist/webtriggers/topSlowestStatementLastHourTrigger.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"topSlowestStatementLastHourTrigger.d.ts","sourceRoot":"","sources":["../../src/webtriggers/topSlowestStatementLastHourTrigger.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,8BAA8B,CAAC;AASjE,OAAO,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AAcjE,UAAU,cAAc;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,aAAa,CAAC,EAAE,aAAa,CAAC;IAC9B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,qBAAqB,GAAG,6BAA6B,CAAC;CAChE;AA2BD,UAAU,eAAe;IACvB,OAAO,EAAE;QAAE,cAAc,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;IACtC,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;CACd;AAgWD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoFG;AACH;;;;;;GAMG;AACH,eAAO,MAAM,kCAAkC,GAC7C,KAAK,iBAAiB,EACtB,UAAU,cAAc,KACvB,OAAO,CAAC,eAAe,CAoDzB,CAAC"}