Perfil de alocação

Página que detalha o perfil de alocação no ClickHouse

O ClickHouse usa o jemalloc como alocador global. O jemalloc inclui ferramentas de amostragem e profiling de alocação.

O ClickHouse e o Keeper permitem controlar a amostragem usando configurações, configurações de consulta, comandos SYSTEM e comandos de quatro letras (4LW) no Keeper. Há várias maneiras de inspecionar os resultados:

• Coletar amostras em system.trace_log sob o tipo JemallocSample para análise por consulta.
• Visualizar estatísticas de memória em tempo real e obter perfis de heap por meio da interface web integrada do jemalloc (26.2+).
• Consultar o perfil de heap atual diretamente via SQL usando system.jemalloc_profile_text (26.2+).
• Analisar a fragmentação de memória via SQL usando system.jemalloc_sampled_allocations (26.9+).
• Gravar perfis de heap em disco e analisá-los com jeprof.

Este guia se aplica às versões 25.9+. Para versões anteriores, consulte o perfil de alocação para versões anteriores à 25.9.

​

Amostragem de alocações

Para fazer a amostragem e traçar o perfil das alocações, inicie o ClickHouse/Keeper com a configuração jemalloc_enable_global_profiler habilitada:

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

jemalloc fará a amostragem das alocações e armazenará as informações internamente.

Você também pode ativar a amostragem por consulta usando a configuração jemalloc_enable_profiler.

Aviso

Como o ClickHouse é um aplicativo com uso intensivo de alocação de memória, a amostragem do jemalloc pode causar sobrecarga de desempenho.

​

Armazenando amostras do jemalloc em system.trace_log

Você pode armazenar amostras do jemalloc em system.trace_log como o tipo JemallocSample. Para habilitar isso globalmente, use a configuração 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>

Aviso

Como o ClickHouse é uma aplicação que faz uso intensivo de alocações, coletar todas as amostras em system.trace_log pode gerar uma carga elevada.

Você também pode habilitar isso por consulta usando a configuração jemalloc_collect_profile_samples_in_trace_log.

​

Exemplo: analisando o uso de memória de uma consulta

Primeiro, execute uma consulta com o profiler do jemalloc habilitado e colete as amostras em 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.

Se o ClickHouse foi iniciado com jemalloc_enable_global_profiler, você não precisa habilitar jemalloc_enable_profiler. O mesmo vale para jemalloc_collect_global_profile_samples_in_trace_log e jemalloc_collect_profile_samples_in_trace_log.

Faça o flush de system.trace_log:

SYSTEM FLUSH LOGS trace_log

Em seguida, consulte-o para obter o uso cumulativo de memória ao longo do tempo:

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

Encontre o momento em que o uso de memória foi mais alto:

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
)

Usando esse resultado, veja quais pilhas de alocação estavam mais ativas no momento de pico:

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

​

Interface web do jemalloc

Esta seção se aplica às versões 26.2+.

O ClickHouse fornece uma interface web integrada para visualizar estatísticas de memória do jemalloc no endpoint HTTP /jemalloc. Ela exibe métricas de memória em tempo real com gráficos, incluindo memória alocada, ativa, residente e mapeada, além de estatísticas por arena e por bin. Você também pode buscar perfis de heap globais e por consulta diretamente pela interface web.

ClickHouse

http://localhost:8123/jemalloc

A interface web do servidor inclui todas as abas: Summary, Allocations, Arenas, Operations, Global Profiler, Query Profiler, Fragmentation e Raw Output.

Keeper

http://localhost:9182/jemalloc

A interface web do Keeper está disponível na porta de controle HTTP. Essa porta fica desabilitada por padrão e deve ser habilitada explicitamente definindo keeper_server.http_control.port na configuração do Keeper:

<clickhouse>
    <keeper_server>
        <http_control>
            <port>9182</port>
        </http_control>
    </keeper_server>
</clickhouse>

Depois de habilitada, a interface web fornece as mesmas visualizações que o servidor — Summary, Allocations, Arenas, Operations, Global Profiler e Raw Output — exceto pelas abas Query Profiler e Fragmentation, que exigem acesso SQL às tabelas de sistema.

Segurança

A porta de controle HTTP do Keeper não tem autenticação no nível da aplicação. Diferentemente da interface web do jemalloc do ClickHouse Server — em que todas as consultas de dados passam pelo handler HTTP de SQL e exigem credenciais de usuário/senha — os endpoints da API REST do Keeper não exigem autenticação. Isso é consistente com outros endpoints de controle HTTP do Keeper (commands, storage, dashboard).

Restrinja o acesso a essa porta usando controles no nível da rede: configure o Keeper para escutar em localhost, use regras de firewall ou coloque-o atrás de um proxy reverso com autenticação. Quando nenhum listen_host é configurado, o Keeper passa a escutar somente em localhost por padrão.

O Keeper também expõe endpoints de API REST para acesso programático:

• GET /jemalloc/stats — saída bruta de malloc_stats_print
• GET /jemalloc/status — estado do profiling em JSON (prof_enabled, prof_active, thread_active_init, lg_sample)
• GET /jemalloc/profile?format={collapsed|raw} — gera um perfil de heap com simbolização no lado do servidor e retorna pilhas colapsadas adequadas para renderização de flame graph (padrão) ou o dump bruto do jemalloc

​

Obtendo perfis de heap por SQL

Esta seção se aplica às versões 26.2+.

A tabela de sistema system.jemalloc_profile_text permite obter e visualizar o perfil de heap atual do jemalloc diretamente por SQL, sem precisar de ferramentas externas nem de gravá-lo em disco antes.

A tabela tem uma única coluna:

Coluna	Tipo	Descrição
line	String	Linha do perfil de heap do jemalloc simbolizado.

Você pode consultar a tabela diretamente — não é necessário gravar um perfil de heap antes:

SELECT * FROM system.jemalloc_profile_text

​

Formato de saída

O formato de saída é controlado pela configuração jemalloc_profile_text_output_format, que oferece suporte a três valores:

• raw — perfil de heap bruto, gerado pelo jemalloc.
• symbolized — formato compatível com o jeprof, com símbolos de função incorporados. Como os símbolos já estão incorporados, o jeprof pode analisar a saída sem precisar do binário do ClickHouse.
• collapsed (padrão) — pilhas colapsadas compatíveis com FlameGraph, uma pilha por linha com a contagem de bytes.

Por exemplo, para obter o perfil bruto:

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

Para obter uma saída simbolizada:

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

​

Configurações adicionais

• jemalloc_profile_text_symbolize_with_inline (Bool, padrão: true) — Define se frames inline devem ser incluídos na simbolização. Desabilitar isso acelera significativamente a simbolização, mas reduz a precisão, pois chamadas de função inline não aparecerão nas stacks. Afeta apenas os formatos symbolized e collapsed.
• jemalloc_profile_text_collapsed_use_count (Bool, padrão: false) — Ao usar o formato collapsed, agrega por contagem de alocações em vez de bytes.

​

Exemplo: gerando um flame graph com SQL

Como o formato de saída padrão é collapsed, você pode passar a saída diretamente para o FlameGraph:

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

Para gerar um flame graph com base na contagem de alocações, em vez de bytes:

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

​

Analisando a fragmentação a partir do SQL

Esta seção se aplica às versões 26.9+.

O jemalloc atende alocações pequenas a partir de slabs: blocos de memória de tamanho fixo divididos em regiões de uma única size class. Um slab só é liberado quando todas as suas regiões estão livres. Se a maior parte das alocações de uma size class é liberada rapidamente, mas algumas delas permanecem vivas por muito tempo, os slabs continuam retidos com a maioria das regiões livres. A memória permanece residente, mas não está alocada. É isso que fragmentação significa aqui.

Duas tabelas de sistema ajudam a descobrir de onde ela vem:

• system.jemalloc_arena_bins mostra quanta memória cada size class desperdiça em cada arena. waste são os bytes retidos em slabs, mas não utilizados por alocações vivas. purpose identifica arenas dedicadas (mergetree, jit, cache); elas guardam dados de vida longa por design, então filtre-as com purpose = '' ao investigar fragmentação inesperada. system.jemalloc_bins traz os mesmos dados somados entre as arenas.
• system.jemalloc_sampled_allocations lista as alocações amostradas que estão vivas no momento, uma linha por sample: o backtrace (trace), há quanto tempo está viva (age_ns), o tamanho e a size class, e a arena. Ler a tabela provoca o flush de um novo perfil de heap.

Fazer o join das duas por arena e size class mostra qual código alocou os objetos antigos nas size classes que desperdiçam memória.

Tenha em mente, ao ler os resultados:

• Apenas threads com o profiler enabled produzem samples (jemalloc_enable_global_profiler na config ou a configuração jemalloc_enable_profiler).
• Cada linha representa cerca de weight alocações reais, e alocações pequenas são amostradas raramente. Ajuste jemalloc_profiler_sampling_rate se as size classes que lhe interessam não tiverem samples.
• Alocações amostradas não são armazenadas em slabs, portanto não contribuem para waste por si mesmas. Elas apenas indicam qual código aloca naquela size class.
• Cada sample vivo custa duas páginas extras (128 KiB em builds com pages de 64 KiB) até que a alocação seja liberada. Desabilitar o profiler impede novos samples, mas não libera os existentes.

A consulta a seguir lista os backtraces de alocações com mais de um minuto de vida nas size classes que desperdiçam mais de 1 MiB:

WITH 60e9 AS min_age_ns
SELECT
    b.arena,
    b.size AS reg_size,
    b.waste AS class_waste,
    s.est_old_objects,
    s.stack
FROM system.jemalloc_arena_bins AS b
INNER JOIN
(
    SELECT
        arena,
        size_class,
        sum(weight) AS est_old_objects,
        arrayStringConcat(arrayMap(a -> demangle(addressToSymbol(a)), arrayReverse(trace)), ';') AS stack
    FROM system.jemalloc_sampled_allocations
    WHERE age_ns > min_age_ns
    GROUP BY arena, size_class, trace
) AS s ON s.size_class = b.index AND s.arena = b.arena
WHERE b.large = 0 AND b.purpose = '' AND b.waste > 1048576
ORDER BY b.waste DESC, s.est_old_objects DESC
SETTINGS allow_introspection_functions=1

​

Exemplo: gerando um flame graph de fragmentação

A mesma consulta pode distribuir o desperdício de cada size class entre seus backtraces, proporcionalmente ao número de alocações antigas, e imprimir o resultado no formato collapsed para o flamegraph.pl. As size classes que apresentam desperdício, mas não têm samples suficientemente antigos, ficam sob um frame [unattributed], de modo que o total do flame graph corresponde ao desperdício total. Leia system.jemalloc_sampled_allocations apenas uma vez por consulta: cada leitura faz o flush de um novo profile, portanto duas subqueries veriam dados diferentes.

WITH 60e9 AS min_age_ns
SELECT format('{} {}',
    if(s.est_old_objects > 0, s.stack, format('[unattributed];arena_{}_class_{}', toString(b.arena), toString(b.size))),
    toString(toUInt64(if(s.est_old_objects > 0, b.waste * s.est_old_objects / sum(s.est_old_objects) OVER (PARTITION BY b.arena, b.index), b.waste))))
FROM system.jemalloc_arena_bins AS b
LEFT JOIN
(
    SELECT
        arena,
        size_class,
        sum(weight) AS est_old_objects,
        arrayStringConcat(arrayMap(a -> demangle(addressToSymbol(a)), arrayReverse(trace)), ';') AS stack
    FROM system.jemalloc_sampled_allocations
    WHERE age_ns > min_age_ns
    GROUP BY arena, size_class, trace
) AS s ON s.size_class = b.index AND s.arena = b.arena
WHERE b.large = 0 AND b.purpose = '' AND b.waste > 0
SETTINGS allow_introspection_functions=1

clickhouse-client -q "..." | flamegraph.pl --color=mem --title="Fragmentation Flame Graph" --width 2400 > result.svg

​

Gravando perfis de heap no disco

Se você precisar salvar perfis de heap como arquivos para análise offline com jeprof, poderá gravá-los no disco.

Por padrão, o arquivo de perfil de heap será gerado em /tmp/jemalloc_clickhouse._pid_._seqnum_.heap, em que _pid_ é o PID do ClickHouse e _seqnum_ é o número de sequência global do perfil de heap atual. No Keeper, o arquivo padrão é /tmp/jemalloc_keeper._pid_._seqnum_.heap e segue as mesmas regras.

Para gravar o perfil atual:

ClickHouse

SYSTEM JEMALLOC FLUSH PROFILE

Ele retornará o local do perfil gravado.

Keeper

echo jmfp | nc localhost 9181

É possível definir outro local adicionando a opção prof_prefix à variável de ambiente MALLOC_CONF. Por exemplo, se você quiser gerar perfis na pasta /data, em que o prefixo do nome do arquivo será my_current_profile, poderá executar o ClickHouse/Keeper com a seguinte variável de ambiente:

MALLOC_CONF=prof_prefix:/data/my_current_profile

O PID e o número de sequência serão acrescentados ao prefixo do arquivo gerado.

​

Analisando arquivos de perfil de heap com jeprof

Após gravar os perfis de heap em disco, eles podem ser analisados usando a ferramenta do jemalloc chamada jeprof. Ela pode ser instalada de várias formas:

• Usando o gerenciador de pacotes do sistema
• Clonando o repositório do jemalloc e executando autogen.sh a partir da pasta raiz. Isso disponibilizará o script jeprof na pasta bin

Há vários formatos de saída disponíveis. Execute jeprof --help para ver a lista completa de opções.

​

Perfis de heap simbolizados

A partir da versão 26.1+, o ClickHouse gera automaticamente perfis de heap simbolizados quando você executa SYSTEM JEMALLOC FLUSH PROFILE. O perfil simbolizado (com a extensão .symbolized) contém símbolos de função incorporados e pode ser analisado com o jeprof sem exigir o binário do ClickHouse.

Por exemplo, quando você executa:

SYSTEM JEMALLOC FLUSH PROFILE

O ClickHouse retornará o caminho para o profile simbolizado (por exemplo, /tmp/jemalloc_clickhouse.12345.0.heap.symbolized).

Em seguida, você poderá analisá-lo diretamente com jeprof:

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

Nenhum binário necessário: Ao usar perfis simbolizados (arquivos .symbolized), você não precisa fornecer o caminho do binário do ClickHouse ao jeprof. Isso facilita muito a análise de perfis em máquinas diferentes ou depois que o binário tiver sido atualizado.

Se você tiver um perfil de heap mais antigo, sem símbolos, e ainda tiver acesso ao binário do ClickHouse, poderá usar a abordagem tradicional:

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

Para perfis não simbolizados, jeprof usa addr2line para gerar stacktraces, o que pode ser bem lento. Se esse for o caso, recomenda-se instalar uma implementação alternativa da ferramenta.

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

Como alternativa, llvm-addr2line funciona igualmente bem (mas observe que llvm-objdump não é compatível com jeprof)

Depois, use-o assim: jeprof --tools addr2line:/usr/bin/llvm-addr2line,nm:/usr/bin/llvm-nm,objdump:/usr/bin/objdump,c++filt:/usr/bin/llvm-cxxfilt

Ao comparar dois perfis, você pode usar o argumento --base:

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

​

Exemplos

Usando perfis simbolizados (recomendado):

• Gere um arquivo de texto com cada procedimento em uma linha:

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

• Gere um arquivo PDF com o grafo de chamadas:

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

Usando perfis não simbolizados (requer o binário):

• Gere um arquivo de texto com cada procedimento em uma linha:

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

• Gere um arquivo PDF com um grafo de chamadas:

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

​

Gerando um flame graph

jeprof permite gerar pilhas colapsadas para criar flame graphs.

Você precisa usar o argumento --collapsed:

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

Ou com um perfil sem símbolos:

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

Depois disso, você pode usar várias ferramentas para visualizar pilhas colapsadas.

A mais popular é o FlameGraph, que contém um script chamado flamegraph.pl:

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

Outra ferramenta interessante é o speedscope, que permite analisar as stacks coletadas de forma mais interativa.

​

Opções adicionais para o profiler

O jemalloc oferece muitas opções relacionadas ao profiler. Elas podem ser controladas modificando a variável de ambiente MALLOC_CONF. Por exemplo, o intervalo entre as amostras de alocação pode ser controlado com lg_prof_sample. Se você quiser gerar o heap profile a cada N bytes, pode ativá-lo usando lg_prof_interval.

Recomenda-se consultar a página de referência do jemalloc para obter uma lista completa das opções.

​

Outros recursos

ClickHouse/Keeper expõem métricas relacionadas ao jemalloc de várias formas.

Aviso

É importante ter em mente que nenhuma dessas métricas é sincronizada com as outras, e os valores podem divergir.

​

Tabela de sistema asynchronous_metrics

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

Referência

​

Tabela de sistema jemalloc_bins

Contém informações sobre alocações de memória feitas pelo alocador jemalloc em diferentes classes de tamanho (bins), agregadas a partir de todas as arenas.

Referência

​

Tabela do sistema jemalloc_stats (26.2+)

Retorna toda a saída de malloc_stats_print() como uma única string. Equivalente ao comando SYSTEM JEMALLOC STATS.

SELECT * FROM system.jemalloc_stats

​

Prometheus

Todas as métricas relacionadas ao jemalloc de asynchronous_metrics também são expostas por meio do endpoint do Prometheus, tanto no ClickHouse quanto no Keeper.

Referência

​

Comando 4LW jmst no Keeper

O Keeper é compatível com o comando 4LW jmst, que retorna estatísticas básicas do alocador:

echo jmst | nc localhost 9181