Профилирование выделений памяти

ClickHouse использует jemalloc в качестве глобального аллокатора. Jemalloc включает инструменты для сэмплирования и профилирования выделений памяти.

ClickHouse и Keeper позволяют управлять сэмплированием с помощью конфигураций, настроек запроса, команд SYSTEM и команд с четырьмя буквами (4LW) в Keeper. Существует несколько способов просмотреть результаты:

• Собирайте сэмплы в system.trace_log с типом JemallocSample для анализа на уровне отдельных запросов.
• Просматривайте статистику памяти в реальном времени и получайте профили кучи через встроенный веб‑интерфейс jemalloc (26.2+).
• Запрашивайте текущий профиль кучи напрямую из SQL с помощью system.jemalloc_profile_text (26.2+).
• Сбрасывайте профили кучи на диск и анализируйте их с помощью jeprof.

Примечание

Это руководство применимо к версиям 25.9+. Для более старых версий см. раздел профилирование выделений памяти для версий до 25.9.

Сэмплирование выделений памяти

Чтобы выполнять сэмплирование и профилирование выделений памяти, запустите ClickHouse/Keeper с включённой настройкой jemalloc_enable_global_profiler:

<clickhouse>
    <jemalloc_enable_global_profiler>1</jemalloc_enable_global_profiler>
</clickhouse>

jemalloc будет выборочно отслеживать выделения памяти и сохранять эту информацию во внутренних структурах.

Вы также можете включить сэмплирование по каждому запросу с помощью настройки jemalloc_enable_profiler.

Предупреждение

Поскольку ClickHouse — приложение с интенсивным использованием выделения памяти, выборочное отслеживание jemalloc может привести к дополнительным накладным расходам и снижению производительности.

Хранение выборок jemalloc в system.trace_log

Вы можете хранить выборки jemalloc в system.trace_log с типом записи JemallocSample. Чтобы включить это глобально, используйте параметр конфигурации jemalloc_collect_global_profile_samples_in_trace_log:

<clickhouse>
    <jemalloc_collect_global_profile_samples_in_trace_log>1</jemalloc_collect_global_profile_samples_in_trace_log>
</clickhouse>

Предупреждение

Поскольку ClickHouse — приложение с большим количеством операций выделения памяти, сбор всех сэмплов в system.trace_log может привести к значительной нагрузке.

Вы также можете включить это для отдельного запроса, используя настройку jemalloc_collect_profile_samples_in_trace_log.

Пример анализа использования памяти запросом

Сначала выполните запрос с включённым профилировщиком памяти jemalloc и соберите сэмплы в system.trace_log:

SELECT *
FROM numbers(1000000)
ORDER BY number DESC
SETTINGS max_bytes_ratio_before_external_sort = 0
FORMAT `Null`
SETTINGS jemalloc_enable_profiler = 1, jemalloc_collect_profile_samples_in_trace_log = 1

Query id: 8678d8fe-62c5-48b8-b0cd-26851c62dd75

Ok.

0 rows in set. Elapsed: 0.009 sec. Processed 1.00 million rows, 8.00 MB (108.58 million rows/s., 868.61 MB/s.)
Peak memory usage: 12.65 MiB.

Примечание

Если ClickHouse был запущен с jemalloc_enable_global_profiler, вам не нужно включать jemalloc_enable_profiler. То же самое относится к jemalloc_collect_global_profile_samples_in_trace_log и jemalloc_collect_profile_samples_in_trace_log.

Очистим system.trace_log:

SYSTEM FLUSH LOGS trace_log

Затем выполним по нему запрос, чтобы получить накопленное использование памяти во времени:

WITH per_bucket AS
(
    SELECT
        event_time_microseconds AS bucket_time,
        sum(size) AS bucket_sum
    FROM system.trace_log
    WHERE trace_type = 'JemallocSample'
      AND query_id = '8678d8fe-62c5-48b8-b0cd-26851c62dd75'
    GROUP BY bucket_time
)
SELECT
    bucket_time,
    sum(bucket_sum) OVER (
        ORDER BY bucket_time ASC
        ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW
    ) AS cumulative_size,
    formatReadableSize(cumulative_size) AS cumulative_size_readable
FROM per_bucket
ORDER BY bucket_time

Найдите момент, когда использование памяти было максимальным:

SELECT
    argMax(bucket_time, cumulative_size),
    max(cumulative_size)
FROM
(
    WITH per_bucket AS
    (
        SELECT
            event_time_microseconds AS bucket_time,
            sum(size) AS bucket_sum
        FROM system.trace_log
        WHERE trace_type = 'JemallocSample'
          AND query_id = '8678d8fe-62c5-48b8-b0cd-26851c62dd75'
        GROUP BY bucket_time
    )
    SELECT
        bucket_time,
        sum(bucket_sum) OVER (
            ORDER BY bucket_time ASC
            ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW
        ) AS cumulative_size,
        formatReadableSize(cumulative_size) AS cumulative_size_readable
    FROM per_bucket
    ORDER BY bucket_time
)

Используя этот результат, определите, какие стеки выделения памяти были наиболее активны в момент пика:

SELECT
    concat(
        '\n',
        arrayStringConcat(
            arrayMap(
                (x, y) -> concat(x, ': ', y),
                arrayMap(x -> addressToLine(x), allocation_trace),
                arrayMap(x -> demangle(addressToSymbol(x)), allocation_trace)
            ),
            '\n'
        )
    ) AS symbolized_trace,
    sum(s) AS per_trace_sum
FROM
(
    SELECT
        ptr,
        sum(size) AS s,
        argMax(trace, event_time_microseconds) AS allocation_trace
    FROM system.trace_log
    WHERE trace_type = 'JemallocSample'
      AND query_id = '8678d8fe-62c5-48b8-b0cd-26851c62dd75'
      AND event_time_microseconds <= '2025-09-04 11:56:21.737139'
    GROUP BY ptr
    HAVING s > 0
)
GROUP BY ALL
ORDER BY per_trace_sum ASC

Веб-интерфейс jemalloc

Примечание

Этот раздел применим к версиям 26.2+.

ClickHouse предоставляет встроенный веб-интерфейс для просмотра статистики использования памяти jemalloc по HTTP-эндпоинту /jemalloc. Он отображает актуальные метрики памяти с графиками, включая выделенную, активную, резидентную и отображённую (mapped) память, а также статистику по аренам и бинaм. Также вы можете получать глобальные и по отдельным запросам профили кучи напрямую из интерфейса.

Чтобы получить к нему доступ, откройте в браузере:

http://localhost:8123/jemalloc

Получение heap-профилей через SQL

Примечание

Этот раздел актуален для версий 26.2+.

Системная таблица system.jemalloc_profile_text позволяет получать и просматривать текущий heap-профиль jemalloc непосредственно из SQL, без необходимости использования внешних инструментов или предварительной записи на диск.

Таблица содержит один столбец:

Column	Type	Description
line	String	Строка из символизированного heap-профиля jemalloc.

Вы можете выполнять запрос к таблице напрямую — нет необходимости предварительно сбрасывать heap-профиль:

SELECT * FROM system.jemalloc_profile_text

Формат вывода

Формат вывода управляется параметром jemalloc_profile_text_output_format, который поддерживает три значения:

• raw — необработанный heap-профиль в том виде, в котором его формирует jemalloc.
• symbolized — формат, совместимый с jeprof, со встроенными символами функций. Поскольку символы уже встроены, jeprof может анализировать вывод без необходимости в исполняемом файле ClickHouse.
• collapsed (по умолчанию) — свернутые стеки, совместимые с FlameGraph: по одному стеку на строку с указанием количества байт.

Например, чтобы получить необработанный профиль:

SELECT * FROM system.jemalloc_profile_text
SETTINGS jemalloc_profile_text_output_format = 'raw'

Чтобы получить символизированный вывод:

SELECT * FROM system.jemalloc_profile_text
SETTINGS jemalloc_profile_text_output_format = 'symbolized'

Дополнительные настройки

• jemalloc_profile_text_symbolize_with_inline (Bool, по умолчанию: true) — Нужно ли включать inline‑кадры при символизации. Отключение этого параметра значительно ускоряет символизацию, но снижает точность, так как встроенные вызовы функций не будут отображаться в стеках. Влияет только на форматы symbolized и collapsed.
• jemalloc_profile_text_collapsed_use_count (Bool, по умолчанию: false) — При использовании формата collapsed агрегировать по количеству выделений памяти, а не по байтам.

Пример: построение флеймграфа по SQL

Поскольку формат вывода по умолчанию — collapsed, вы можете передать результат напрямую в FlameGraph:

clickhouse-client -q "SELECT * FROM system.jemalloc_profile_text" | flamegraph.pl --color=mem --title="Allocation Flame Graph" --width 2400 > result.svg

Чтобы построить flame graph по числу аллокаций, а не по объёму в байтах:

clickhouse-client -q "SELECT * FROM system.jemalloc_profile_text SETTINGS jemalloc_profile_text_collapsed_use_count = 1" | flamegraph.pl --color=mem --title="Allocation Count Flame Graph" --width 2400 > result.svg

Сброс профилей кучи на диск

Если вам нужно сохранить профили кучи в виде файлов для офлайн-анализа с помощью jeprof, вы можете сбросить их на диск.

По умолчанию файл профиля кучи создаётся в /tmp/jemalloc_clickhouse._pid_._seqnum_.heap, где _pid_ — это PID ClickHouse, а _seqnum_ — глобальный порядковый номер для текущего профиля кучи. Для Keeper файл по умолчанию — /tmp/jemalloc_keeper._pid_._seqnum_.heap и подчиняется тем же правилам.

Чтобы сбросить текущий профиль:

ClickHouse

SYSTEM JEMALLOC FLUSH PROFILE

Команда вернёт путь к сброшенному профилю.

Keeper

echo jmfp | nc localhost 9181

Другое местоположение можно задать, дополнив переменную окружения MALLOC_CONF опцией prof_prefix. Например, если вы хотите генерировать профили в каталоге /data, где префиксом имени файла будет my_current_profile, вы можете запустить ClickHouse/Keeper со следующей переменной окружения:

MALLOC_CONF=prof_prefix:/data/my_current_profile

К префиксу имени сгенерированного файла будут добавлены PID и порядковый номер.

Анализ файлов профилей кучи с помощью jeprof

После того как профили кучи были сброшены на диск, их можно проанализировать с помощью инструмента jemalloc под названием jeprof. Его можно установить несколькими способами:

• С помощью системного менеджера пакетов
• Клонировать репозиторий jemalloc и запустить autogen.sh из корневого каталога. В результате в каталоге bin появится скрипт jeprof.

Доступно множество различных форматов вывода. Запустите jeprof --help, чтобы увидеть полный список опций.

Символизированные профили кучи

Начиная с версии 26.1+ ClickHouse автоматически генерирует символизированные профили кучи при выполнении команды SYSTEM JEMALLOC FLUSH PROFILE. Символизированный профиль (с расширением .symbolized) содержит встроенные символы функций и может анализироваться с помощью jeprof без необходимости в исполняемом файле ClickHouse.

Например, при выполнении:

SYSTEM JEMALLOC FLUSH PROFILE

ClickHouse вернёт путь к символизированному профилю (например, /tmp/jemalloc_clickhouse.12345.0.heap.symbolized).

Затем вы можете напрямую проанализировать его с помощью jeprof:

jeprof /tmp/jemalloc_clickhouse.12345.0.heap.symbolized --output_format [ > output_file]

Примечание

Бинарный файл не требуется: При использовании символизированных профилей (файлы .symbolized) вам не нужно указывать путь к бинарнику ClickHouse для jeprof. Это значительно упрощает анализ профилей на разных машинах или после обновления бинарного файла.

Если у вас есть старый несимволизированный профиль кучи и по-прежнему есть доступ к бинарному файлу ClickHouse, вы можете использовать традиционный подход:

jeprof path/to/clickhouse path/to/heap/profile --output_format [ > output_file]

Примечание

Для несимволизированных профилей jeprof использует addr2line для генерации стек-трейсов, что может работать очень медленно. В таком случае рекомендуется установить альтернативную реализацию этого инструмента.

git clone https://github.com/gimli-rs/addr2line.git --depth=1 --branch=0.23.0
cd addr2line
cargo build --features bin --release
cp ./target/release/addr2line path/to/current/addr2line

В качестве альтернативы можно использовать llvm-addr2line — он работает не хуже (но обратите внимание, что llvm-objdump не совместим с jeprof).

После этого используйте его следующим образом: jeprof --tools addr2line:/usr/bin/llvm-addr2line,nm:/usr/bin/llvm-nm,objdump:/usr/bin/objdump,c++filt:/usr/bin/llvm-cxxfilt

При сравнении двух профилей вы можете использовать аргумент --base:

jeprof --base /path/to/first.heap.symbolized /path/to/second.heap.symbolized --output_format [ > output_file]

Примеры

Использование символизированных профилей (рекомендуется):

• Создайте текстовый файл, в котором каждая процедура указана в отдельной строке:

jeprof /tmp/jemalloc_clickhouse.12345.0.heap.symbolized --text > result.txt

• Сгенерируйте PDF-файл с графом вызовов:

jeprof /tmp/jemalloc_clickhouse.12345.0.heap.symbolized --pdf > result.pdf

Использование несиволизированных профилей (требуется бинарник):

• Сгенерируйте текстовый файл, в котором каждая процедура указана в отдельной строке:

jeprof /path/to/clickhouse /tmp/jemalloc_clickhouse.12345.0.heap --text > result.txt

• Создайте PDF-файл с графом вызовов:

jeprof /path/to/clickhouse /tmp/jemalloc_clickhouse.12345.0.heap --pdf > result.pdf

Построение flame-графа

jeprof позволяет получать свернутые стеки вызовов для построения flame-графов.

Для этого следует использовать аргумент --collapsed:

jeprof /tmp/jemalloc_clickhouse.12345.0.heap.symbolized --collapsed > result.collapsed

Или с профилем без символов:

jeprof /path/to/clickhouse /tmp/jemalloc_clickhouse.12345.0.heap --collapsed > result.collapsed

После этого вы можете использовать различные инструменты для визуализации свернутых стеков.

Самый популярный из них — FlameGraph, который содержит скрипт flamegraph.pl:

cat result.collapsed | /path/to/FlameGraph/flamegraph.pl --color=mem --title="Allocation Flame Graph" --width 2400 > result.svg

Еще один полезный инструмент — speedscope, который позволяет более интерактивно анализировать собранные стеки.

Дополнительные параметры профилировщика

У jemalloc есть множество параметров, относящихся к профилировщику. Ими можно управлять, изменяя переменную окружения MALLOC_CONF. Например, интервал между выборками операций выделения памяти можно контролировать с помощью lg_prof_sample. Если вы хотите создавать дамп профиля кучи каждые N байт, вы можете включить это с помощью lg_prof_interval.

Рекомендуется ознакомиться со справочной страницей jemalloc для получения полного перечня параметров.

Другие ресурсы

ClickHouse/Keeper предоставляют метрики, связанные с jemalloc, множеством разных способов.

Warning

Важно понимать, что ни одна из этих метрик не синхронизирована с другими, и значения со временем могут расходиться.

Системная таблица asynchronous_metrics

SELECT *
FROM system.asynchronous_metrics
WHERE metric LIKE '%jemalloc%'
FORMAT Vertical

Справочник

Системная таблица jemalloc_bins

Содержит информацию о выделении памяти, выполненном через аллокатор jemalloc в разных классах размеров (bins), агрегированную по всем аренам.

Справочник

Системная таблица jemalloc_stats (26.2+)

Возвращает полный вывод malloc_stats_print() в виде единой строки. Эквивалентно команде SYSTEM JEMALLOC STATS.

SELECT * FROM system.jemalloc_stats

Prometheus

Все метрики, связанные с jemalloc из asynchronous_metrics, также доступны через конечную точку Prometheus как в ClickHouse, так и в Keeper.

Справочник

Команда jmst 4LW в Keeper

Keeper поддерживает команду jmst 4LW, которая возвращает базовую статистику аллокатора:

echo jmst | nc localhost 9181