Blog do Seba

DBA, Consultor, Instrutor, [aprendiz de] Ninja e metido a Chef nas horas vagas!

Utilizando API do pgconfig.org

Created in Nov 5, 2016

1100 Words. Read in about 5 Min.
Categories: PostgreSQL PGCOnfig
Tags: curl rest API tips

Já falei do pgconfig.org antes. Ele, até o momento, é uma ferramenta que faz sugestões de tuning do PostgreSQL. Acesse o site e mata a curiosidade de como funciona. Eu espero, fique tranquilo.

Hoje eu quero comentar um pouco mais sobre como ele funciona, e explicar como você pode usar sua API nos seus projetos/scripts/coisas divertidas sem depender mais da interface web.

Como funciona

Na prática, a interface web (que agora vou chamar de UI), acessa a api no endereço https://api.pgconfig.org/v1/tuning/get-config. Caso você queira simular a chamada, é só clicar no link que eu citei, mas já que o foco é automatizar as coisas, faça o mesmo teste como curl:

$ curl 'https://api.pgconfig.org/v1/tuning/get-config'
{"data": [{"category": "memory_related","description": "Memory Configuration","parameters": [{"config_value": "512MB","format": "Bytes","name": "shared_buffers"},{"config_value": "2GB","format": "Bytes","name": "effective_cache_size"},{"config_value": "20MB","format": "Bytes","name": "work_mem"},{"config_value": "128MB","format": "Bytes","name": "maintenance_work_mem"}]},{"category": "checkpoint_related","description": "Checkpoint Related Configuration","parameters": [{"config_value": "512MB","format": "Bytes","name": "min_wal_size"},{"config_value": "2GB","format": "Bytes","name": "max_wal_size"},{"config_value": 0.7,"format": "Float","name": "checkpoint_completion_target"},{"config_value": "15MB","format": "Bytes","name": "wal_buffers"}]},{"category": "network_related","description": "Network Related Configuration","parameters": [{"config_value": "*","format": "String","name": "listen_addresses"},{"config_value": 100,"format": "Decimal","name": "max_connections"}]}],"jsonapi": {"version": "1.0"},"links": {"self": "http://api.pgconfig.org/v1/tuning/get-config"},"meta": {"arguments": {},"copyright": "PGConfig API","version": "2.0 beta"}}

Ok, já que o JSON+API que a URL retona fica um pouco dificil de ler, eu vou formatar ele pra você:

{  
   "data":[  
      {  
         "category":"memory_related",
         "description":"Memory Configuration",
         "parameters":[  
            {  
               "config_value":"512MB",
               "format":"Bytes",
               "name":"shared_buffers"
            },
            {  
               "config_value":"2GB",
               "format":"Bytes",
               "name":"effective_cache_size"
            },
            {  
               "config_value":"20MB",
               "format":"Bytes",
               "name":"work_mem"
            },
            {  
               "config_value":"128MB",
               "format":"Bytes",
               "name":"maintenance_work_mem"
            }
         ]
      },
      {  
         "category":"checkpoint_related",
         "description":"Checkpoint Related Configuration",
         "parameters":[  
            {  
               "config_value":"512MB",
               "format":"Bytes",
               "name":"min_wal_size"
            },
            {  
               "config_value":"2GB",
               "format":"Bytes",
               "name":"max_wal_size"
            },
            {  
               "config_value":0.7,
               "format":"Float",
               "name":"checkpoint_completion_target"
            },
            {  
               "config_value":"15MB",
               "format":"Bytes",
               "name":"wal_buffers"
            }
         ]
      },
      {  
         "category":"network_related",
         "description":"Network Related Configuration",
         "parameters":[  
            {  
               "config_value":"*",
               "format":"String",
               "name":"listen_addresses"
            },
            {  
               "config_value":100,
               "format":"Decimal",
               "name":"max_connections"
            }
         ]
      }
   ],
   "jsonapi":{  
      "version":"1.0"
   },
   "links":{  
      "self":"http://api.pgconfig.org/v1/tuning/get-config"
   },
   "meta":{  
      "arguments":{  

      },
      "copyright":"PGConfig API",
      "version":"2.0 beta"
   }
}

Basicamente, os dados importantes estão dentro de "data", aonde são agrupados por categoria, igualzinho no site. ;)

Uma coisa importante sobre isso é que você pode formatar a saida apresentada de forma mais conveniente, apenas informando o parâmetro format=conf, conforme o exemplo abaixo:

$ curl 'https://api.pgconfig.org/v1/tuning/get-config?format=conf'
# Generated by PGConfig 2.0 beta
## http://pgconfig.org

# Memory Configuration
shared_buffers = 512MB
effective_cache_size = 2GB
work_mem = 20MB
maintenance_work_mem = 128MB

# Checkpoint Related Configuration
min_wal_size = 512MB
max_wal_size = 2GB
checkpoint_completion_target = 0.7
wal_buffers = 15MB

# Network Related Configuration
listen_addresses = '*'
max_connections = 100

Outras opções para o format são json(que é a default) e alter_system, veja:

$ curl 'https://api.pgconfig.org/v1/tuning/get-config?format=alter_system'
-- Generated by PGConfig 2.0 beta
---- http://pgconfig.org

-- Memory Configuration
ALTER SYSTEM SET shared_buffers TO '512MB';
ALTER SYSTEM SET effective_cache_size TO '2GB';
ALTER SYSTEM SET work_mem TO '20MB';
ALTER SYSTEM SET maintenance_work_mem TO '128MB';

-- Checkpoint Related Configuration
ALTER SYSTEM SET min_wal_size TO '512MB';
ALTER SYSTEM SET max_wal_size TO '2GB';
ALTER SYSTEM SET checkpoint_completion_target TO '0.7';
ALTER SYSTEM SET wal_buffers TO '15MB';

-- Network Related Configuration
ALTER SYSTEM SET listen_addresses TO '*';
ALTER SYSTEM SET max_connections TO '100';

Pegou a idéia aqui? pra mudar a saida, tudo o que você precisa é ir informando os parâmetros na URL.

Parâmetros disponíveis

A relação abaixo lista os parâmetros disponíveis:

Parâmetro Possíveis valores Valor padrão Descrição
pg_version da versão 9.0 até a 9.6 9.6 Informa a versão do PostgreSQL
total_ram qualquer valor acima de 1GB 2GB Quantidade de memória dedicada ao PostgreSQL.
max_connections qualquer valor acima de 1 100 Quantidade esperada de conexões
env_name WEB, OLTP, DW, Mixed e Desktop WEB Define o ambiente que o servidor vai rodar (mais detalhes abaixo)
os_type Linux, Windows e Unix Linux Define o tipo do sistema operacional utilizado
arch x86-64 e i686 x86-64 Define a arquitetura do servidor
format json, conf e alter_system json Muda o formato de saída
show_doc true e false false Mostra a documentação (valido apenas pro formato json)
include_pgbadger true e false false Adiciona as configurações para habilitar o pgbadger

Importante Não esqueça de, ao informar o parâmetro total_ram, passar o valor formatado conforme a expressão [0-9]{1,}GB, por exemplo: 4GB.

Sobre o ambiente

A relação abaixo explica um pouco mais sobre os ambientes:

Nome Descrição Exemplos de uso
WEB Aplicações web geral Aplicações com perfil web, como um portal ou aplicativo corporativo
OLTP Aplicações com grande volume de transações Sistemas do tipo ERP ou grandes sistemas corporativos com muitas transações simultâneas
DW Aplicações de DataWare House Sistemas de BI em geral
Mixed Ambientes que compartilham o banco e a aplicação no mesmo servidor Pequenos sistemas, normalmente rodando na web
Desktop Ambiente de desenvolvimento Máquina de desenvolvimento, suporte ou pré-vendas

Exemplo completo

Segue abaixo um exemplo completo, igualzinho ao utilizado pela UI:

$ curl 'https://api.pgconfig.org/v1/tuning/get-config?env_name=WEB&format=alter_system&include_pgbadger=true&log_format=stderr&max_connections=100&pg_version=9.6&total_ram=2GB'

Como são calculadas os valores?

A fim de deixar o processo mais claro, eu criei uma entrada na API pra listar as regras. Ele pode ser acessado na URL abaixo:

Importante: A chamada pra esse contexto permite filtrar os_type, arch e env_name.

Os dados que contem detalhes de como cada parâmetro é caculado são formula e max_value, por exemplo:

...
"format": "Bytes",
"formula": "TOTAL_RAM / 4",
"max_value": "2047MB",
"name": "shared_buffers"
...

Note que os valores são influenciados pelos filtros citados acima.

Exemplo de chamada

Recomendo que você abra a URL no navegador pra facilitar a visualização (ou formate o json):

curl 'https://api.pgconfig.org/v1/tuning/get-rules?os_type=Windows&arch=i686&env_name=OLTP'

Outras opções da API

Endereço Descrição exemplo de saída
/v1/tuning/get-config-all-environments Lista as regras pra todos os ambientes 
...
"data": [
    {
    "configuration": [..],
    "environment": "WEB"
    },
    {
    "configuration": [..],
    "environment": "OLTP"
    },
    {
    "configuration": [..],
    "environment": "DW"
    },
    {
    "configuration": [..],
    "environment": "Mixed"
    },
    {
    "configuration": [..],
    "environment": "Desktop"
    }
]
...
/v1/tuning/list-enviroments Lista todos os ambientes 
...
"data": [
    "WEB",
    "OLTP",
    "DW",
    "Mixed",
    "Desktop"
],
...
/v1/generators/pgbadger/get-config Lista as configurações do pgbadger (aceita o parametro format) 
...
"data": [
    {
    "category": "log_config",
    "description": "Logging configuration for pgbadger",
    "parameters": [
        {
        "config_value": "on",
        "name": "logging_collector"
        },
        {
        "config_value": "on",
        "name": "log_checkpoints"
        },
        {
        "config_value": "on",
        "name": "log_connections"
        },
        {
        "config_value": "on",
        "name": "log_disconnections"
        },
        {
        "config_value": "on",
        "name": "log_lock_waits"
        },
        {
        "config_value": "0",
        "name": "log_temp_files"
        },
        {
        "config_value": "C",
        "format": "String",
        "name": "lc_messages"
        },
        {
        "comment": "Adjust the minimum time to collect data",
        "config_value": "10s",
        "format": "Time",
        "name": "log_min_duration_statement"
        },
        {
        "config_value": "0",
        "name": "log_autovacuum_min_duration"
        }
    ]
},
...

Outras opções estão sendo desenvolvidas e em breve vou postar mais detalhes.

Comentários

comments powered by Disqus