StarRocks Backend (BE) nodes expose detailed memory metrics and accept configuration parameters that let you control how much memory each workload category can consume. This topic describes the memory usage categories, explains the BE and session configuration parameters, and shows how to inspect memory usage at runtime.
Memory usage categories
Each BE tracks memory consumption across the following categories. The metrics are exposed at the /metrics endpoint and visible in the mem_tracker interface.
| Label | Metric name | Description | BE configuration parameter |
|---|---|---|---|
process | starrocks_be_process_mem_bytes | Memory actually used by the BE process, excluding reserved free memory | mem_limit |
query_pool | starrocks_be_query_mem_bytes | Total memory used by the query layer of the BE | N/A |
load | starrocks_be_load_mem_bytes | Total memory used by import tasks | load_process_max_memory_limit_bytes, load_process_max_memory_limit_percent |
table_meta | starrocks_be_tablet_meta_mem_bytes | Total memory used by metadata | N/A |
compaction | starrocks_be_compaction_mem_bytes | Total memory used by multi-version memory compaction | compaction_max_memory_limit, compaction_max_memory_limit_percent |
column_pool | starrocks_be_column_pool_mem_bytes | Column pool memory used to accelerate data reads at the storage layer | N/A |
page_cache | starrocks_be_storage_page_cache_mem_bytes | Page cache at the storage layer of the BE | disable_storage_page_cache, storage_page_cache_limit |
chunk_allocator | starrocks_be_chunk_allocator_mem_bytes | Per-CPU-core cache that accelerates small memory chunk allocation | chunk_reserved_bytes_limit |
consistency | starrocks_be_consistency_mem_bytes | Memory used by periodic consistency check tasks | consistency_max_memory_limit, consistency_max_memory_limit_percent |
schema_change | starrocks_be_schema_change_mem_bytes | Total memory used by schema change tasks | memory_limitation_per_thread_for_schema_change |
clone | starrocks_be_clone_mem_bytes | Total memory used by tablet clone tasks | N/A |
update | starrocks_be_update_mem_bytes | Total memory used by the primary key model | N/A |
Modify BE memory configuration parameters
To add or modify BE memory configuration parameters in the EMR console:
On the EMR on ECS page, find the StarRocks cluster and click Services in the Actions column.
On the Services tab, click Configure in the StarRocks section.
On the Configure tab, click the be.conf tab.
Modify existing parameters or click Add Configuration Item to add new ones.
For details, see Manage configuration items.
Memory configuration parameters
BE configuration parameters
The following parameters are set in be.conf.
| Parameter | Default value | Description |
|---|---|---|
mem_limit | 90% | Maximum percentage of total server memory the BE can use. The hard limit is 90% and the soft limit is 80%. If the BE shares the server with other memory-intensive services, lower this value to avoid memory contention. |
load_process_max_memory_limit_bytes | 107,374,182,400 | Maximum memory that import tasks can use in total, in bytes. The effective limit is min(mem_limit × load_process_max_memory_limit_percent / 100, load_process_max_memory_limit_bytes). When the limit is reached, StarRocks triggers disk flush and applies backpressure to slow ingestion. |
load_process_max_memory_limit_percent | 30 | Maximum percentage of mem_limit that import tasks can use collectively. Works with load_process_max_memory_limit_bytes; the smaller computed value takes effect. |
compaction_max_memory_limit | -1 | Maximum memory a compaction task can use, in bytes. The effective limit is min(mem_limit × compaction_max_memory_limit_percent / 100, compaction_max_memory_limit). The default value -1 means no limit. Keep the default unless compaction is consuming excessive memory; if the limit is exceeded, the compaction task fails. |
compaction_max_memory_limit_percent | 100 | Maximum percentage of mem_limit that compaction tasks can use. Works with compaction_max_memory_limit; the smaller computed value takes effect. |
disable_storage_page_cache | true | Whether to disable the page cache at the storage layer. Set to false to enable page cache when memory is sufficient and queries scan large amounts of data repeatedly — this can significantly improve query performance. Use together with storage_page_cache_limit to bound cache size. |
storage_page_cache_limit | 0 | Maximum memory for the storage-layer page cache. Takes effect only when disable_storage_page_cache is false. |
chunk_reserved_bytes_limit | 2,147,483,648 | Maximum memory for the per-CPU-core cache used to accelerate small memory chunk allocation. Default is 2,147,483,648 bytes (2 GB). Increase this value if memory is plentiful and you want to reduce allocation overhead. |
consistency_max_memory_limit | 10G | Maximum memory a consistency check task can use. The effective limit is min(mem_limit × consistency_max_memory_limit_percent / 100, consistency_max_memory_limit). If the limit is exceeded, the consistency check task fails. |
consistency_max_memory_limit_percent | 20 | Maximum percentage of mem_limit that consistency check tasks can use. Works with consistency_max_memory_limit; the smaller computed value takes effect. |
memory_limitation_per_thread_for_schema_change | 2 | Memory limit per thread for schema change tasks. If the limit is exceeded, the schema change task fails. |
tc_use_memory_min | 10,737,418,240 | Minimum memory reserved for TCMalloc. If TCMalloc's reserved memory falls below this threshold, StarRocks stops returning free memory to the operating system. |
Session variables
The following variables apply per session and can be set with the SET statement.
| Variable | Default value | Description |
|---|---|---|
exec_mem_limit | 2,147,483,648 | Memory limit for a single query instance, in bytes. |
load_mem_limit | 0 | Memory limit for a single import task, in bytes. The default value 0 means the value of exec_mem_limit is used. |
View memory usage
Use the metrics interface
The metrics endpoint updates every 10 seconds. Run the following command to retrieve all BE memory metrics:
# The default web server port of a BE is 8040.
curl -XGET -s http://<BE_IP>:8040/metrics | grep "^starrocks_be_.*_mem_bytes\|^starrocks_be_tcmalloc_bytes_in_use"For a description of each metric, see Memory usage categories.
Use the mem_tracker interface
The mem_tracker interface provides a hierarchical view of memory usage. Access it in a browser or with cURL:
http://<be_ip>:8040/mem_trackerThe interface displays the following fields:
| Field | Description |
|---|---|
level | MemTracker uses a tree structure. Level 1 is the total memory used by the BE. Level 2 shows individual memory usage categories. |
Label | Identifies the memory usage category. See Memory usage categories for the full list. |
Parent | The label of the parent node in the tree. |
Limit | The memory usage limit for this node. none means no limit is set. |
Current Consumption | Current memory usage. |
Peak Consumption | The memory usage during peak hours. |