Skip to content
ClickHouse Docs
ClickHouse DocsClickHouse Docs
49.6kGet Started

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

View as MarkdownEdit this pageReport an issueSet up docs MCP

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

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

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

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

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

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

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

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

Хранение образцов 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>

Вы также можете включать это для отдельных запросов с помощью настройки 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.

Сбросьте 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

ClickHouse предоставляет встроенный веб-интерфейс для просмотра статистики памяти jemalloc по HTTP-конечной точке /jemalloc. Он показывает метрики памяти в реальном времени в виде графиков, включая allocated, active, resident и mapped memory, а также статистику по arena и bin. Вы также можете получать глобальные профили кучи и профили кучи отдельных запросов напрямую из интерфейса.

http://localhost:8123/jemalloc

Интерфейс сервера включает все вкладки: Summary, Allocations, Arenas, Operations, Global Profiler, Query Profiler и Raw Output.

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

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

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

Столбец Тип Описание
line String Строка из символизированного профиля кучи jemalloc.

К таблице можно обращаться напрямую — предварительно записывать профиль кучи на диск не требуется:

SELECT * FROM system.jemalloc_profile_text

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

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

  • raw — необработанный профиль кучи, созданный 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) — Включать ли инлайн-фреймы при символизации. Отключение этого параметра значительно ускоряет символизацию, но снижает точность, поскольку инлайн-вызовы функций не будут отображаться в стеках. Влияет только на форматы 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

Чтобы построить флеймграф по числу аллокаций, а не по байтам:

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; для него действуют те же правила.

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

SYSTEM JEMALLOC FLUSH PROFILE

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

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

MALLOC_CONF=prof_prefix:/data/my_current_profile

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

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

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

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

Доступно множество различных форматов вывода. Полный список параметров можно посмотреть, выполнив 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]

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

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

При сравнении двух профилей можно использовать аргумент --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

Создание флеймграфа

jeprof позволяет формировать свёрнутые стеки для построения флеймграфов.

Нужно использовать аргумент --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, различными способами.

Системная таблица 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
Navigation