pg_shmemviz: nova ferramenta abre a memória compartilhada do PostgreSQL byte a byte

O DBA que já precisou entender de fato o que está dentro da memória compartilhada do PostgreSQL↳PostgreSQL11 conteúdosPostgreSQL via SSL com GolangData · abr 20195 itens legais sobre data types do PostgreSQLData · mar 20195 serviços gratuitos na cloud para bancos de dados PostgresData · fev 2025Ver tudo em Data → conhece o limite das views existentes. pg_shmem_allocations, pg_buffercache e pg_shmem_allocations_numa respondem perguntas específicas, mas não mostram onde uma alocação está fisicamente, quais estruturas C ela contém, o padding do compilador ou os bytes efetivamente gravados. É esse vazio que o pg_shmemviz busca preencher, anunciado em 19 de agosto de 2026 e disponível na versão v0.1.0-beta.1.

A ferramenta segue a mesma abordagem do pg_walviz: trazer layout físico e navegação byte a byte, só que aplicada à memória compartilhada em vez dos segmentos de WAL. Em resumo, é um instrumento de desenvolvimento e depuração que captura os segmentos de shared memory principal e dinâmica em um snapshot offline e os apresenta em um navegador local.

O que a interface mostra

O viewer combina quatro painéis sincronizados: um mapa da memória compartilhada, uma tabela de alocações, um inspetor de estruturas e uma visão de bytes físicos (Physical Bytes). Selecionar uma alocação, um campo de estrutura ou um byte atualiza os demais painéis, e a navegação por ponteiros e histórico pode cruzar os segmentos capturados.

O mapa exibe alocações nomeadas, o padding do alocador e faixas não utilizadas. Memória principal, controle de DSM, segmentos DSM e áreas DSA podem ser selecionados de forma independente, com filtro na tabela de alocações e zoom em uma faixa física específica.

O ponto mais interessante para quem investiga internals é o painel Structure Fields, que lê o DWARF do executável postgres exato para exibir estruturas C aninhadas, offsets de campos, valores, padding do compilador e padding de stride de arrays. Ponteiros com limites conhecidos aparecem como regiões referenciadas: ao selecionar um, a ferramenta destaca o ponteiro de origem e abre os bytes do alvo. Há descoberta especializada para estruturas de estatísticas, WAL, processos, SLRU, dynahash e o registro de DSM.

Na visão Physical Bytes, cada byte é classificado por campo de estrutura e padding. Passar o mouse sobre um byte mostra endereço, offset, valor, campo correspondente, nó NUMA e informação de comparação quando disponível.

Buffer cache, DSA e NUMA

Com o pg_buffercache instalado, o snapshot passa a incluir um resumo do buffer cache, com detalhe opcional por buffer: identificador, banco, tablespace, relation, fork, bloco, estado dirty, contador de uso e backends que fizeram pin. É possível capturar nomes resolvidos de objetos e navegar direto do descritor do buffer para sua página.

Segmentos de memória compartilhada dinâmica são exibidos separadamente do segmento principal, com os nomes do registro de DSM identificando segmentos DSM simples, áreas DSA nomeadas e áreas DSA que sustentam tabelas dshash conhecidas.

Em um build com --with-libnuma, o mapa mostra a colocação de páginas capturada, propagada para alocações, instâncias de estruturas, campos, regiões referenciadas e bytes físicos. Como uma faixa pode cruzar o limite de página, um mesmo intervalo pode aparecer em vários nós. No exemplo, um PGPROC selecionado se estende pelos nós 0 e 1, e seu membro subxids e o array xids aninhado também cruzam a fronteira, com elementos individuais mostrando placement próprio (um elemento em N0 enquanto o pai aparece como N0+N1).

Comparação de snapshots

Dois snapshots compatíveis podem ser comparados nos níveis de alocação, campo e byte. O controle Before/After preserva as seleções correspondentes ao navegar entre as duas capturas. No exemplo, xact_commit muda de 1736 para 1952: o campo de oito bytes é contornado na visão Physical Bytes, e apenas os bytes cujo valor mudou ficam marcados em roxo. Para diagnosticar o que efetivamente se alterou entre dois instantes, é um recurso valioso.

Como instalar e capturar

O servidor precisa ter informação de debug, e o pg_config, o executável postgres e os arquivos de desenvolvimento correspondentes devem estar disponíveis. A ferramenta usa LLDB no macOS e GDB nos demais sistemas. Importante: o debugger lê o DWARF do executável e não faz attach ao servidor em execução.

A compilação e instalação da extensão seguem o padrão:

cd ~/pg_shmemviz
make PG_CONFIG=/path/to/postgres-install/bin/pg_config
make PG_CONFIG=/path/to/postgres-install/bin/pg_config install

Depois cria-se a extensão no banco usado para captura:

psql -d postgres -c 'CREATE EXTENSION pg_shmemviz'

A captura do snapshot:

~/pg_shmemviz/bin/pg_shmemviz capture \
  --pg-config /path/to/postgres-install/bin/pg_config \
  --dbname postgres \
  /path/to/new-snapshot

E o viewer, que sobe um servidor HTTP local em 127.0.0.1:8765 por padrão:

~/pg_shmemviz/bin/pg_shmemviz serve /path/to/new-snapshot

Para servidor remoto ou headless, use --no-open --port 8765 e um túnel SSH a partir da estação de trabalho:

ssh -N -L 8765:127.0.0.1:8765 user@server

Os avisos que não devem ser ignorados

Aqui entra o critério que todo DBA responsável deve aplicar. O próprio autor é enfático: não execute o pg_shmemviz em uma instância PostgreSQL de produção. Ele foi projetado para desenvolvimento e depuração em instâncias descartáveis ou isoladas. Vale detalhar as razões técnicas por trás disso:

• A captura é uma cópia sequencial e sem lock da memória compartilhada viva. O PostgreSQL continua modificando os dados, então campos relacionados podem representar instantes diferentes e um campo multibyte não atômico pode aparecer "torn" (partido).
• O segmento principal completo é copiado, incluindo shared buffers e espaço reservado não utilizado. Os snapshots podem ser grandes e conter dados sensíveis.
• A captura NUMA pode causar fault em páginas ainda não tocadas e definir sua colocação de first-touch.
• O viewer não tem autenticação, autorização nem TLS. Deve permanecer em loopback, com acesso remoto apenas via túnel SSH.
• A descoberta automática de estruturas depende de nomes internos do PostgreSQL e, por ora, foi validada contra o PostgreSQL 20devel.

Para quem vale o tempo

Esta é uma ferramenta de nicho, e é honesto dizê-lo. Não substitui pg_buffercache no dia a dia nem serve para monitoramento contínuo. O público real é quem desenvolve extensões, contribui com o core, estuda internals ou precisa entender de forma cirúrgica como uma estrutura ocupa a memória, incluindo padding e placement NUMA em máquinas multi-nó. Para esse perfil, poder navegar de uma alocação até o byte cru, com os campos das structs C anotados a partir do DWARF, economiza horas de GDB manual.

É um beta, e o autor pede feedback. O código está no repositório oficial, com a lista completa de compatibilidade e limitações no README. Vale acompanhar a evolução, mas com a disciplina de sempre: instância isolada, nunca produção.

Fonte: Planet PostgreSQL