Introdução aos insights do Cloud SQL

O Cloud SQL Insights ajuda a detectar, diagnosticar e evitar problemas de desempenho de consultas nos bancos de dados do Cloud SQL. Eles oferecem serviço de autoatendimento, monitoramento intuitivo e diagnóstico além da detecção, para identificar a causa raiz dos problemas de desempenho.

Neste codelab, você vai aprender a configurar uma instância do Cloud SQL para PostgreSQL, implantar um aplicativo Node.js para usar a instância do Cloud SQL como armazenamento de back-end e depois usar o Cloud SQL Insights para visualizar e monitorar consultas.

Pré-requisitos

• Noções básicas sobre a linguagem de programação Node.js e ferramentas

Atividades deste laboratório

• Usar o Cloud SQL em um aplicativo Node.js.
• Ativar o comentarista de SQL em um aplicativo Node.js.
• Use o Cloud SQL Insights para monitorar e investigar o desempenho da consulta.

Pré-requisitos

• Uma conta do Google Cloud em que você tenha permissões para ativar APIs e criar serviços

Configuração de ambiente personalizada

1. Faça login no Console do Cloud e crie um novo projeto ou reutilize um existente. Crie uma se ainda não tiver uma conta do Gmail ou do Google Workspace.

Lembre-se do ID do projeto que você está usando. Faremos referência a ele mais adiante neste codelab como PROJECT-ID.

2. Em seguida, será necessário ativar o faturamento no Console do Cloud para usar os recursos do Google Cloud.

A execução deste codelab não será muito cara, se for o caso. Siga todas as instruções na seção "Limpar e saber mais", que ensina a encerrar os recursos para que você não tenha cobranças além deste tutorial. Novos usuários do Google Cloud estão qualificados para o programa de avaliação gratuita de US$ 300.

Ativar o Cloud Shell

1. No Console do Cloud, clique em Ativar o Cloud Shell.

Se você nunca tiver iniciado o Cloud Shell, verá uma tela intermediária (abaixo da dobra) com a descrição do que ele é. Se esse for o caso, clique em Continuar e você não o verá novamente. Esta é uma tela única:

Leva apenas alguns instantes para provisionar e se conectar ao Cloud Shell.

Essa máquina virtual contém todas as ferramentas de desenvolvimento necessárias. Ela oferece um diretório principal persistente de 5 GB, além de ser executada no Google Cloud. Isso aprimora o desempenho e a autenticação da rede.

2. Execute o seguinte comando no Cloud Shell para confirmar que você está usando o projeto correto:

Depois de se conectar ao Cloud Shell, você já estará autenticado e o projeto já estará configurado com seu ID do projeto.

Observação: a ferramenta de linha de comando gcloud é a poderosa e unificada do Google Cloud. Ela vem pré-instalado no Cloud Shell. Essa ferramenta aceita preenchimento com tabulação. Para mais informações, consulte a visão geral da ferramenta de linha de comando gcloud.

Execute o seguinte comando para confirmar se você está usando o projeto correto.

gcloud config list project

Se você quiser usar um projeto diferente do que selecionou ao abrir o Cloud Shell, defina um novo projeto executando:

gcloud config set project <PROJECT-ID>;

1. Depois que o Cloud Shell for iniciado, use a linha de comando para criar uma nova instância do Cloud SQL chamada my-instance com o Cloud SQL Insights ativado:

Observação: neste codelab, você ativa o Cloud SQL Insights por meio da linha de comando deste codelab. No entanto, também pode ser ativado no Console pelo menu "Query Insights" da instância.

gcloud sql instances create my-instance --tier db-f1-micro --database-version=POSTGRES_12 --region=us-central --root-password=<PASSWORD> --insights-config-query-insights-enabled --insights-config-record-application-tags --insights-config-record-client-address

Veja uma breve explicação das sinalizações e o que elas significam:

• A sinalização --tier db-f1-micro está especificando um tipo de máquina com recursos mínimos, já que isso serve para fins de desenvolvimento e você não precisa de muitos recursos para o codelab. Saiba mais sobre os níveis.
• A sinalização --database-version=POSTGRES_12 cria uma instância que será a versão 12 do PostgreSQL.
• A sinalização --region=us-central especifica a região em que a instância será criada.
• A sinalização --root-password=<PASSWORD> permite que você especifique a senha do usuário raiz postgres. Lembre-se de substituir <PASSWORD> por uma senha de sua escolha.
• A sinalização --insights-config-query-insights-enabled ativa o Cloud SQL Insights na instância.
• A sinalização --insights-config-record-application-tags permite que as tags do aplicativo sejam registradas. Você saberá mais sobre tags de aplicativos em seções posteriores.
• A sinalização --insights-config-record-client-address permite que os endereços IP do cliente sejam registrados pelo Cloud SQL Insights.

Talvez você precise ativar a API sqladmin.googleapis.com no projeto. Se for solicitado, selecione y para ativar a API.

A criação da instância levará alguns minutos. Após a conclusão dessa operação, sua instância estará pronta para uso.

2. Crie um banco de dados que você usará para o aplicativo de amostra:

gcloud sql databases create votesdb --instance my-instance

Também é possível acessar e configurar a instância por meio do Console do Cloud.

3. Receba o nome da conexão da instância no formato PROJECT-ID:ZONE-ID:INSTANCE-ID executando o comando a seguir. Você usará isso posteriormente na configuração do aplicativo Node.js.

gcloud sql instances describe my-instance | grep connectionName

As contas de serviço são usadas para conceder permissões de uso de serviços diferentes no projeto do GCP. Para este codelab, você precisa de uma permissão para conceder ao Cloud SQL Proxy permissão para se conectar à sua instância do Cloud SQL.

Crie uma conta de serviço no Console

1. Acesse a página de contas de serviço do IAM e clique no botão na parte superior da página.
2. Atribua um nome e um código exclusivos à sua conta de serviço e clique em CRIAR.
3. Na próxima página, clique na lista suspensa "Selecionar um papel". Filtre por "Cloud SQL" e selecione o papel de cliente do Cloud SQL. Clique em Continuar e depois em Concluído.
4. Depois que a conta de serviço tiver sido criada, clique nos três pontos em Ações da sua nova conta de serviço e escolha "Criar chave". JSON será selecionado, mantenha o padrão e clique em CRIAR. Um arquivo de chave privada .json será salvo. Clique em Fechar.
5. No Cloud Shell, clique nos três pontos do menu Mais e escolha Fazer upload de arquivo. Procure e faça o download do arquivo .json na sua máquina local. Isso fará upload do arquivo .json no diretório principal do Cloud Shell.

Você usará o Cloud SQL Proxy para comunicação entre o aplicativo e a instância do banco de dados.

1. Faça o download do Cloud SQL Proxy: No Cloud Shell, é possível executar:

wget https://dl.google.com/cloudsql/cloud_sql_proxy.linux.amd64 -O cloud_sql_proxy && chmod +x cloud_sql_proxy

2. Para executar o proxy, use o nome da conexão da instância que você copiou dos detalhes da instância do Cloud SQL para substituir <INSTANCE_CONNECTION_NAME>. Para o arquivo de credencial, insira o caminho para o arquivo que você enviou na última etapa.

./cloud_sql_proxy -credential_file=/path/to/credential_file.json -instances=<INSTANCE_CONNECTION_NAME>=tcp:5432 &

Se a operação for bem-sucedida, você verá algumas linhas de saída, terminando com uma mensagem Ready for new connections.

1. Clone o repositório do aplicativo de amostra e instale os pacotes necessários para executar o aplicativo.

git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples/

cd nodejs-docs-samples/cloud-sql/postgres/knex

npm install

2. Configure as variáveis de ambiente a seguir:

export CLOUD_SQL_CONNECTION_NAME='<PROJECT-ID>:<ZONE-ID>:<INSTANCE-ID>'
export DB_HOST='127.0.0.1:5432'
export DB_USER='postgres>'
export DB_PASS='<PASSWORD>'
export DB_NAME='votesdb'

3. Execute createTable.js para criar a tabela de banco de dados que o aplicativo exige e garantir que o banco de dados esteja configurado corretamente e, em seguida, inicie o aplicativo de amostra.

node createTable.js $DB_USER $DB_PASS $DB_NAME $CLOUD_SQL_CONNECTION_NAME votes $DB_HOST

npm start

4. Clique em Visualização da Web no Cloud Shell e selecione Visualizar na porta 8080.

Você verá o aplicativo de votação "Guias" e "Espaços", como mostrado aqui no navegador:

5. Clique nos botões para votar e salvar alguns dados no banco de dados.

Como este aplicativo de exemplo é muito simples, você adicionará uma página adicional que exibe todos os votos. O principal motivo para fazer isso é que você tem mais dados para observar ao usar o Cloud SQL Insights mais tarde.

1. Digite Ctrl+c no Cloud Shell para interromper o aplicativo de amostra.
2. No Cloud Shell, clique no botão para iniciar o editor.
3. No "Explorador de arquivos", localize nodejs-docs-samples/cloud-sql/postgres/knex/server.js e clique nele para carregar o arquivo server.js no editor.

Adicione o seguinte código depois de definir a função getVotes:

/**
 * Retrieve all vote records from the database.
 *
 * @param {object} pool The Knex connection object.
 * @returns {Promise}
 */
const getAllVotes = async pool => {
  return await pool
    .select('candidate', 'time_cast')
    .from('votes')
    .orderBy('time_cast', 'desc');
};

4. Adicione o seguinte código para a rota '/getAllVotes' abaixo, em que as outras rotas são definidas:

app.get('/getAllVotes', async (req, res) => {
  pool = pool || createPool();
  try {
    // Query all votes from the database.
    const votes = await getAllVotes(pool);

    res.render('allvotes.pug', {
      votes: votes,
    });
  } catch (err) {
    console.error(err);
    res
      .status(500)
      .send('Unable to load page; see logs for more details.')
      .end();
  }
});

5. Crie um novo arquivo no diretório nodejs-docs-samples/cloud-sql/postgres/knex/views chamado allvotes.pug. Cole o seguinte código:

doctype html
html(lang="en")
  head
    title Tabs VS Spaces

    link(rel="stylesheet", href="https://cdnjs.cloudflare.com/ajax/libs/materialize/1.0.0/css/materialize.min.css")
    link(rel="stylesheet", href="https://fonts.googleapis.com/icon?family=Material+Icons")
    script(src="https://cdnjs.cloudflare.com/ajax/libs/materialize/1.0.0/js/materialize.min.js")
  body

    nav(class="red lighten-1")
      div(class="nav-wrapper")
        a(href="#" class="brand-logo center") Tabs VS Spaces

    div(class="section")

      h4(class="header center") Recent Votes
      ul(class="container collection center")
        each vote in votes
          li(class="collection-item avatar")
            if vote.candidate.trim() === 'TABS'
              i(class="material-icons circle green") keyboard_tab
            else
              i(class="material-icons circle blue") space_bar
            span(class="title") A vote for <b>#{vote.candidate}</b>
            p was cast at #{vote.time_cast}.

6. Clique no botão para retornar ao Cloud Shell e executar:

npm start

7. Abra o aplicativo no Web Preview para verificar se ele está funcionando. Adicione /getAllVotes ao URL no navegador para visualizar a nova página que você adicionou.

Agora você instalará e ativará o SQL Reviewer, uma biblioteca de código aberto que permite que os ORMs incrementem instruções SQL com comentários antes da execução. O SQLcommenter é compatível com vários ORMs e frameworks, incluindo aquele usado pelo aplicativo de amostra: Knex.js. O Cloud SQL Insights usa as informações nesses comentários para fornecer uma visualização do aplicativo no desempenho do banco de dados e identificar qual código do aplicativo está causando problemas. A sobrecarga de desempenho é pequena, e você pode encontrar mais informações sobre o desempenho na documentação.

1. Digite Ctrl+c no Cloud Shell para interromper o aplicativo de amostra.
2. Execute o seguinte comando para instalar os pacotes que o SQLcommenter precisa:

  npm install @google-cloud/sqlcommenter-knex @opencensus/nodejs @opencensus/propagation-tracecontext @opentelemetry/api @opentelemetry/core --save

3. No Cloud Shell, clique no botão para iniciar o editor.
4. No "Explorador de arquivos", localize nodejs-docs-samples/cloud-sql/postgres/knex/server.js e clique nele para carregar o arquivo server.js no editor.
5. Localize este código no arquivo:

const process = require('process');

Abaixo dele, adicione o seguinte código

const {wrapMainKnexAsMiddleware} = require('@google-cloud/sqlcommenter-knex');

6. Localize este código no arquivo:

// Set Content-Type for all responses for these routes.
app.use((req, res, next) => {
  res.set('Content-Type', 'text/html');
  next();
});

Abaixo dele, adicione o seguinte código

app.use(wrapMainKnexAsMiddleware(Knex, {
    traceparent: true,
    tracestate: true,
    route: true,
    db_driver: true
}));

Depois disso, seu código deve ficar assim:

...
// Require process, so we can mock environment variables.
const process = require('process');

const {wrapMainKnexAsMiddleware} = require('@google-cloud/sqlcommenter-knex');
const express = require('express');
const bodyParser = require('body-parser');
const Knex = require('knex');

const app = express();
app.set('view engine', 'pug');
app.enable('trust proxy');

// Automatically parse request body as form data.
app.use(bodyParser.urlencoded({extended: false}));
app.use(bodyParser.json());

// Set Content-Type for all responses for these routes.
app.use((req, res, next) => {
  res.set('Content-Type', 'text/html');
  next();
});

app.use(wrapMainKnexAsMiddleware(Knex, {
    traceparent: true,
    tracestate: true,
    route: true,
    db_driver: true
}));
...

7. Clique no botão para retornar ao Cloud Shell e executar:

npm start

8. No aplicativo "Tabs x Spaces", clique nos botões para votar mais votos e adicionar mais dados ao banco de dados.

O painel "Query Insights" ajuda a resolver problemas das consultas do Cloud SQL para procurar problemas de desempenho.

Carga do banco de dados - gráfico de todas as consultas

O painel de insights sobre consultas de nível superior mostra o gráfico Carga do banco de dados all todas consultas.

O gráfico contém informações sobre capacidade da CPU, espera da CPU e da CPU, Espera de E/S e Espera de bloqueio. Saiba mais sobre o que essas métricas significam, onde as métricas são armazenadas, e veja alguns exemplos de como esse gráfico se parece com consultas problemáticas na documentação. No caso deste aplicativo de amostra, a carga de consulta do banco de dados é baixa, portanto, não há picos grandes no gráfico.

Quais consultas são responsáveis pela maioria das cargas?

Abaixo do gráfico, você encontra a tabela QUERIES que contém as consultas normalizadas para o período selecionado. As consultas na tabela são classificadas pelo tempo de execução total.

Você pode clicar em uma consulta para ver informações detalhadas, como carga do banco de dados para essa consulta específica, latência da consulta, amostras do plano de consulta e principais usuários. Se um aplicativo for criado usando um ORM, assim como o caso do aplicativo de exemplo, talvez você não saiba qual parte do aplicativo é responsável por qual consulta. A seção Tags principais pode ajudar você a descobrir isso.

Onde a carga da consulta é originada no aplicativo?

Alterne da tabela QUERIES para a tabela TAGS para ver uma lista de consultas marcadas pela lógica de negócios, o que proporciona uma visão mais centralizada do aplicativo.

Na tabela TAGS, é possível ver a carga do banco de dados dividida por qual rota gerou a carga. Na captura de tela acima, veja que a rota '/getAllVotes' tem um tempo médio de execução maior e tem mais linhas retornadas, em média. Embora o tempo de execução que vemos na tabela não seja problemático nesse caso, vamos clicar na linha de '/getAllVotes' mesmo para analisar os dados em mais detalhes.

Por que as consultas estão sendo executadas lentamente?

Clique no ponto no gráfico Amostras do plano de consulta para ver um plano de consulta.

Os planos de consulta mostram como o PostgreSQL executa uma consulta em segundo plano, o que facilita determinar se há operações que resultam em lentidão.

Qual código do aplicativo está contribuindo para a lentidão?

O Cloud SQL Insights também tem uma visualização contextual do rastreamento de ponta a ponta, o que pode ser útil para fazer uma investigação mais detalhada das partes de um aplicativo que estão gerando consultas lentas.

Clique na guia END TO END para visualizar um trace no contexto.

Observação: saiba mais sobre como usar e interpretar os planos de consulta e o rastreamento completo na documentação.

Você aprendeu a usar o Cloud SQL Insights para monitorar e investigar o desempenho da consulta com um aplicativo Node.js e um banco de dados PostgreSQL do Cloud SQL.

Como fazer a limpeza

Se não quiser manter a instância do Cloud SQL em execução, exclua-a agora.

gcloud sql instances delete my-instance

Saiba mais

• Documentação da visão geral do Cloud SQL Insights
• Como usar a documentação do Cloud SQL Insights
• Documentação do comentarista de SQL
• Repositório github do comentador do SQL