Memory & Resources Monitoring

Memory management is critical for ClickHouse performance. UptimeDock monitors your ClickHouse server's memory usage at both the system and query level, helping you prevent out-of-memory errors and optimize resource utilization.

Overview

ClickHouse is designed for high-performance analytics and can consume significant memory for complex queries, aggregations, and JOIN operations. Proper memory monitoring helps you:

Prevent out-of-memory (OOM) errors that crash queries or the server
Identify memory-intensive queries before they cause problems
Plan capacity for growing workloads
Optimize query patterns to reduce memory consumption

Memory Dashboard

The Memory tab in your ClickHouse check dashboard provides a real-time view of server memory consumption. Data is refreshed periodically (shown as "X minutes ago received").

Quick Access

Navigate to your ClickHouse check and switch between Disk and Memory tabs to view different resource metrics. Click the Alerts button to configure memory alerts.

Memory Metrics Explained

Metric	Description	What to Watch
Total Memory	Total RAM available to the ClickHouse server	Baseline for calculating usage percentages
Used	Amount of memory currently in use	Should stay well below total to allow for query spikes
Free	Available memory for new operations	Low free memory increases OOM risk
Memory Usage %	Percentage of total memory currently in use	Primary metric for alerts; ideally below 70-80%
Max Memory Usage	Peak memory usage since last reset	Indicates worst-case memory consumption
Query Memory	Memory currently allocated to running queries	High values indicate resource-intensive queries in progress
Memory Tracking	Memory tracked by ClickHouse's internal allocator	Helps identify memory not released back to the OS

Understanding Memory Usage

ClickHouse may show different memory values than the operating system. This is because ClickHouse tracks memory it allocates but may not immediately release it to the OS. The Memory Tracking metric shows ClickHouse's internal view of memory usage.

Query-Level Memory Usage

Beyond server-level metrics, UptimeDock tracks memory consumption for individual queries, helping you identify and optimize memory-intensive operations.

Memory in Query Details

When viewing the Query Profile, each query's details include:

Memory Usage (Avg) – Average memory consumed per execution of this query pattern

This helps identify queries that consistently consume significant memory, even if they complete quickly.

Memory in Slow Query Analysis

The Slow Query Details modal provides memory information for each individual slow query execution:

Memory Usage – Peak memory consumed during this specific query execution

Comparing memory usage across slow queries helps you understand if memory consumption contributes to slow execution times.

-- Example: Find queries with highest memory usage
SELECT 
    query,
    formatReadableSize(memory_usage) AS peak_memory,
    query_duration_ms,
    read_rows
FROM system.query_log
WHERE type = 'QueryFinish'
  AND event_time > now() - INTERVAL 1 DAY
ORDER BY memory_usage DESC
LIMIT 10

Setting Up Memory Alerts

Configure alerts to be notified when memory usage exceeds safe thresholds. Click the Alerts button in the Memory dashboard to access alert configuration.

Recommended Thresholds

Alert Type	Warning	Critical	Rationale
Memory Usage %	70%	85%	Leave headroom for query spikes
Query Memory	50% of total	75% of total	Prevent single queries from exhausting memory

Pro Tip

Set conservative thresholds initially and adjust based on your workload patterns. It's better to receive early warnings than to discover issues after an OOM crash.

Troubleshooting Memory Issues

Common memory-related issues and how to resolve them:

Issue	Symptoms	Solution
High baseline memory	Memory usage high even with no queries	Check mark cache, uncompressed cache settings; consider reducing buffer sizes
Memory spikes during queries	Memory jumps dramatically during certain queries	Set `max_memory_usage` per query; optimize GROUP BY and ORDER BY operations
Memory not released	Memory tracking high, but queries finished	ClickHouse may retain memory for performance; restart if critical
OOM kills	Queries fail with memory limit exceeded	Increase limits or optimize queries; consider `max_bytes_before_external_group_by`
Gradual memory growth	Memory increases slowly over time	Check for memory leaks in custom functions; review mutation queue

Useful diagnostic queries:

-- Check current memory usage by component
SELECT 
    metric,
    formatReadableSize(value) AS size
FROM system.asynchronous_metrics
WHERE metric LIKE '%Memory%'
ORDER BY value DESC;

-- Find memory-intensive running queries
SELECT 
    query_id,
    formatReadableSize(memory_usage) AS memory,
    elapsed,
    query
FROM system.processes
ORDER BY memory_usage DESC;

Best Practices

Follow these guidelines to maintain healthy memory usage:

Memory Management Tips

Set max_memory_usage at the user or query level to prevent runaway queries
Use max_bytes_before_external_group_by for large aggregations
Monitor memory trends over time, not just point-in-time values
Schedule memory-intensive operations during low-traffic periods
Consider increasing server RAM if consistently above 70% usage

ClickHouse memory settings to consider:

-- Set per-query memory limit (example: 10GB)
SET max_memory_usage = 10737418240;

-- Use external sorting for large GROUP BY
SET max_bytes_before_external_group_by = 5368709120;

-- Limit memory for all queries from a user
ALTER USER monitoring_user SETTINGS max_memory_usage = 5368709120;