Query Statistics

The Query Engine provides aggregate statistics about query execution patterns, success rates, and performance characteristics. These statistics power dashboards, alerts, and capacity planning decisions.

Endpoint

GET /v1/queries/stats

Required Headers

Header	Type	Description
`X-Tenant-ID`	UUID	The tenant identifier
`Authorization`	String	Bearer JWT token

Query Parameters

Parameter	Type	Default	Description
`days`	int	7	Number of days to include in statistics

Implementation

@GetMapping("/stats")
public ResponseEntity<Map<String, Object>> getStats(
        @RequestHeader("X-Tenant-ID") UUID tenantId,
        @RequestParam(defaultValue = "7") int days) {
 
    Map<String, Object> stats = historyService.getQueryStats(tenantId, days);
    return ResponseEntity.ok(stats);
}

curl Example

# Get query statistics for the last 30 days
curl -s "http://query-engine:8080/v1/queries/stats?days=30" \
  -H "X-Tenant-ID: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer $JWT_TOKEN"

Response

{
  "totalQueries": 12450,
  "completedQueries": 11980,
  "failedQueries": 320,
  "cancelledQueries": 150,
  "successRate": 0.962,
  "averageExecutionTimeMs": 2340,
  "medianExecutionTimeMs": 890,
  "p95ExecutionTimeMs": 8500,
  "p99ExecutionTimeMs": 24000,
  "totalBytesScanned": 1099511627776,
  "cacheHitRate": 0.34,
  "engineDistribution": {
    "TRINO": 8200,
    "CLICKHOUSE": 3800,
    "SPARK_ASYNC": 450
  },
  "statusDistribution": {
    "COMPLETED": 11980,
    "FAILED": 320,
    "CANCELLED": 150,
    "TIMEOUT": 0
  },
  "periodStart": "2026-01-13T00:00:00Z",
  "periodEnd": "2026-02-12T23:59:59Z"
}

Per-Query Execution Statistics

Each QueryResponse includes detailed execution statistics in the statistics field:

{
  "statistics": {
    "cpuTimeMs": 1800,
    "wallTimeMs": 2450,
    "queuedTimeMs": 50,
    "analysisTimeMs": 120,
    "planningTimeMs": 280,
    "peakMemoryBytes": 134217728,
    "inputRows": 5000000,
    "inputBytes": 2147483648,
    "outputRows": 42,
    "outputBytes": 3360,
    "completedSplits": 16
  }
}

Statistics Fields

Field	Description
`cpuTimeMs`	Total CPU time consumed across all workers
`wallTimeMs`	Wall-clock time from start to completion
`queuedTimeMs`	Time spent waiting in the execution queue
`analysisTimeMs`	Time spent parsing and analyzing the SQL
`planningTimeMs`	Time spent generating the execution plan
`peakMemoryBytes`	Peak memory usage during execution
`inputRows`	Total rows read from source tables
`inputBytes`	Total bytes read from source tables
`outputRows`	Rows in the final result set
`outputBytes`	Size of the final result set
`completedSplits`	Number of Trino splits processed

Micrometer Metrics

The Query Engine emits detailed Micrometer metrics for monitoring:

Execution Metrics

Metric	Type	Tags	Description
`query.execution.time`	Timer	`engine`, `status`	Query execution duration
`query.trino.execution`	Timer	--	Trino-specific execution time
`query.cache.hit`	Counter	`tenant`	Cache hit count
`query.cancelled`	Counter	`tenant`	Cancelled query count

Workload Metrics

Metric	Type	Tags	Description
`query.workload.submitted`	Counter	--	Total queries submitted
`query.workload.admitted`	Counter	`path`	Queries admitted (immediate/queued)
`query.workload.rejected`	Counter	`reason`	Queries rejected
`query.workload.completed`	Counter	--	Successfully completed queries
`query.workload.failed`	Counter	--	Failed queries
`query.workload.queue.depth`	Gauge	--	Current queue depth
`query.workload.executing`	Gauge	--	Currently executing queries
`query.workload.memory.utilization`	Gauge	--	Memory pool utilization

Cache Metrics

Metric	Type	Tags	Description
`query.cache.l1.eviction`	Counter	`cause`	L1 cache evictions
`query.cache.l1.put`	Counter	--	L1 cache insertions
`query.cache.l2.put`	Counter	--	L2 cache insertions
`query.cache.l2.error`	Counter	`operation`	L2 cache errors
`query.cache.lookup`	Counter	`level`, `status`	Cache lookup results
`query.cache.lookup.time`	Timer	`level`, `status`	Cache lookup latency
`query.cache.invalidate`	Counter	--	Cache invalidation events

Prometheus Integration

These metrics are exposed via the Spring Actuator Prometheus endpoint:

# Access Prometheus metrics
curl http://query-engine:8080/actuator/prometheus | grep query_execution

Example output:

query_execution_time_seconds_count{engine="TRINO",status="success"} 8420.0
query_execution_time_seconds_sum{engine="TRINO",status="success"} 19782.45
query_execution_time_seconds_max{engine="TRINO",status="success"} 34.2
query_cache_hit_total{tenant="550e8400-e29b-41d4-a716-446655440000"} 4280.0

Query History Overview