perf(database): reserve query traces for problems

Author: chrisbbreuer

config/database.ts

@@ -188,6 +188,12 @@ export default {
      */
     enabled: env.DB_QUERY_LOGGING_ENABLED ?? true,
 
+    /**
+     * Capture caller stacks for successful fast queries too. Slow and failed
+     * queries always retain their caller details.
+     */
+    captureAllTraces: env.DB_QUERY_LOGGING_CAPTURE_ALL_TRACES ?? false,
+
     /**
      * The threshold in milliseconds to mark a query as slow
      */

docs/guide/query-monitoring.md

@@ -11,7 +11,7 @@ The Query Monitoring system provides comprehensive tools to collect, analyze, an
 - **Real-time Query Logging**: Automatically logs all database queries with detailed information
 - **Query Analysis**: Analyzes query patterns, identifies slow queries, and suggests optimizations
 - **Dashboard Interface**: Visual dashboard for monitoring query performance metrics
-- **Detailed Query Information**: Displays query details including duration, status, bindings, and more
+- **Detailed Query Information**: Displays query details including duration, status, bindings, and caller traces for slow or failed queries
 - **Advanced Filtering**: Filter queries by type, status, connection, and more
 - **Optimization Suggestions**: Automated recommendations for improving query performance
 
@@ -27,6 +27,9 @@ export default {
     // Enable or disable query logging
     enabled: true,
 
+    // Also capture caller stacks for successful fast queries
+    captureAllTraces: false,
+
     // Threshold in milliseconds to mark a query as slow
     slowThreshold: 100,
 
@@ -56,6 +59,7 @@ You can also configure query monitoring using environment variables:
 
 ```
 DB_QUERY_LOGGING_ENABLED=true
+DB_QUERY_LOGGING_CAPTURE_ALL_TRACES=false
 DB_QUERY_LOGGING_SLOW_THRESHOLD=100
 DB_QUERY_LOGGING_RETENTION_DAYS=7
 DB_QUERY_LOGGING_PRUNE_FREQUENCY=24
@@ -103,7 +107,7 @@ The detail view provides comprehensive information about a specific query:
 - Full query text and normalized version
 - Execution metrics and duration
 - Bindings and parameters
-- Stack trace and caller information
+- Stack trace and caller information for slow or failed queries
 - Index usage information
 - EXPLAIN plan data
 - Optimization suggestions
@@ -135,11 +139,11 @@ Queries are stored in the `query_logs` table with the following structure:
 | error | text | Error message if failed |
 | executed_at | timestamp | When the query was executed |
 | bindings | text | JSON array of query parameters |
-| trace | text | Stack trace showing where query was called |
-| model | text | Model that executed the query |
-| method | text | Method that executed the query |
-| file | text | File path where query originated |
-| line | integer | Line number where query originated |
+| trace | text | Stack trace for a slow or failed query |
+| model | text | Model that executed a slow or failed query |
+| method | text | Method that executed a slow or failed query |
+| file | text | File path where a slow or failed query originated |
+| line | integer | Line number where a slow or failed query originated |
 | memory_usage | numeric | Memory used during execution |
 | rows_affected | integer | Number of rows affected |
 | transaction_id | text | Related transaction identifier |
@@ -164,7 +168,9 @@ The system includes a scheduled job (`PruneQueryLogsJob`) that automatically rem
 
 4. **Database Impact**: Be aware that query logging itself adds some overhead. Monitor the performance impact and adjust settings accordingly.
 
-5. **Security**: Query logs may contain sensitive information in bindings. Ensure that access to the query dashboard is properly secured.
+5. **Caller Traces**: Slow and failed queries always include caller traces. Enable `captureAllTraces` only when fast-query call sites are worth the additional CPU and storage cost.
+
+6. **Security**: Query logs may contain sensitive information in bindings. Ensure that access to the query dashboard is properly secured.
 
 ## Debugging with Query Logs
 

storage/framework/core/database/src/query-logger.ts

@@ -293,8 +293,12 @@ async function createQueryLogRecord(
   // Get normalized query (replace specific values with placeholders)
   const normalizedQuery = normalizeQuery(query) || query
 
-  // Extract stack trace and caller information
-  const { trace, caller } = extractTraceInfo()
+  // Caller traces are most useful when a query needs investigation. Capturing
+  // an Error stack for every successful fast query is expensive and inflates
+  // the log rows that dominate production traffic.
+  const traceInfo = status === 'completed' && !config.database?.queryLogging?.captureAllTraces
+    ? undefined
+    : extractTraceInfo()
 
   return {
     query,
@@ -305,8 +309,8 @@ async function createQueryLogRecord(
     error: error ? String(error) : undefined,
     executed_at: sqlDateTime(),
     bindings,
-    trace,
-    ...caller,
+    trace: traceInfo?.trace,
+    ...(traceInfo?.caller ?? {}),
     memory_usage: memoryUsage().heapUsed / 1024 / 1024, // in MB
   }
 }

storage/framework/core/database/tests/fixtures/query-logger-dispatch.ts

@@ -160,12 +160,12 @@ try {
         { query: { sql: analyzedSql }, queryDurationMillis: 101 },
       ]
       await Promise.all((slowFirst ? events.reverse() : events).map(logQuery))
-      const records = await db.unsafe('SELECT query, status, affected_tables, tags FROM query_logs WHERE query IN (?, ?)', [ordinarySql, analyzedSql]).execute()
+      const records = await db.unsafe('SELECT query, status, affected_tables, tags, trace FROM query_logs WHERE query IN (?, ?)', [ordinarySql, analyzedSql]).execute()
       const ordinary = records.find(row => row.query === ordinarySql)
       const analyzed = records.find(row => row.query === analyzedSql)
-      if (records.length !== 2 || ordinary?.status !== 'completed' || ordinary.affected_tables !== null || ordinary.tags !== null)
+      if (records.length !== 2 || ordinary?.status !== 'completed' || ordinary.affected_tables !== null || ordinary.tags !== null || ordinary.trace !== null)
         throw new Error('Concurrent ordinary query diagnostics changed')
-      if (analyzed?.status !== 'slow' || analyzed.affected_tables !== '["query_logger_fixture"]' || analyzed.tags !== '["SELECT","table:query_logger_fixture"]')
+      if (analyzed?.status !== 'slow' || analyzed.affected_tables !== '["query_logger_fixture"]' || analyzed.tags !== '["SELECT","table:query_logger_fixture"]' || !String(analyzed.trace).includes('query-logger-dispatch.ts'))
         throw new Error('Concurrent slow query analysis was lost')
     }
   }

storage/framework/core/database/tests/fixtures/query-trace.ts

@@ -11,6 +11,7 @@ initializeDbConfig({
 config.database.queryLogging = {
   ...config.database.queryLogging,
   enabled: true,
+  captureAllTraces: true,
   excludedQueries: [],
   analysis: { ...config.database.queryLogging?.analysis, enabled: false },
 }

storage/framework/core/env/src/types.ts

@@ -142,6 +142,7 @@ export interface FrameworkEnv {
   DB_READ_HOSTS: string | undefined
   DB_READ_AUTO_ROUTE: boolean | undefined
   DB_QUERY_LOGGING_ENABLED: boolean | undefined
+  DB_QUERY_LOGGING_CAPTURE_ALL_TRACES: boolean | undefined
   DB_QUERY_LOGGING_SLOW_THRESHOLD: number | undefined
   DB_QUERY_LOGGING_RETENTION_DAYS: number | undefined
   DB_QUERY_LOGGING_PRUNE_FREQUENCY: number | undefined

storage/framework/defaults/ai/skills/stacks-database/SKILL.md

@@ -259,6 +259,7 @@ Entity-centric API for single-table design:
   migrationLocks: 'migration_locks',
   queryLogging: {
     enabled: true,
+    captureAllTraces: false, // slow and failed queries always keep traces
     slowThreshold: 100,  // ms
     retention: 7,        // days
     pruneFrequency: 24,  // hours