Introduzione a Query Insights per Cloud SQL

1. Prima di iniziare

Query Insights per Cloud SQL consente di rilevare, diagnosticare e prevenire problemi di prestazioni delle query per i database Cloud SQL. Fornisce informazioni di monitoraggio self-service e diagnostiche che vanno oltre il rilevamento per aiutarti a identificare la causa principale dei problemi di prestazioni.

In questo codelab, imparerai a configurare un'istanza Cloud SQL per PostgreSQL, a eseguire il deployment di un'app Node.js in modo da utilizzare l'istanza Cloud SQL come spazio di archiviazione backend e quindi a utilizzare Query Insights per visualizzare e monitorare le query.

Prerequisiti

• Familiarità di base con il linguaggio di programmazione e gli strumenti Node.js

Attività previste

• Utilizzare Cloud SQL in un'app Node.js.
• Abilita il commentatore SQL in un'app Node.js.
• Usa Query Insights per Cloud SQL per monitorare e analizzare le prestazioni delle query.

Che cosa ti serve

• Un account Google Cloud in cui disponi delle autorizzazioni per abilitare le API e creare servizi

2. Configurazione e requisiti

Configurazione dell'ambiente da seguire in modo autonomo

1. Accedi alla console Cloud e crea un nuovo progetto o riutilizzane uno esistente. Se non hai ancora un account Gmail o Google Workspace, devi crearne uno.

Ricorda l'ID del progetto che stai utilizzando. Verrà indicato più avanti in questo codelab come PROJECT-ID.

2. Successivamente, dovrai abilitare la fatturazione in Cloud Console per utilizzare le risorse Google Cloud.

Eseguire questo codelab non dovrebbe costare molto. Assicurati di seguire le istruzioni nella sezione "Pulizia e ulteriori informazioni" in cui viene spiegato come arrestare le risorse in modo da non incorrere in fatturazione oltre questo tutorial. I nuovi utenti di Google Cloud sono idonei al programma prova senza costi di 300$.

Attiva Cloud Shell

1. Dalla console Cloud, fai clic su Attiva Cloud Shell.

Se non hai mai avviato Cloud Shell, verrà visualizzata una schermata intermedia (below the fold) in cui viene descritto di cosa si tratta. In tal caso, fai clic su Continua (e non la vedrai più). Ecco come appare quella singola schermata:

Il provisioning e la connessione a Cloud Shell dovrebbero richiedere solo qualche istante.

Questa macchina virtuale viene caricata con tutti gli strumenti di sviluppo necessari. Offre una home directory permanente da 5 GB e viene eseguita in Google Cloud, migliorando notevolmente le prestazioni di rete e l'autenticazione.

2. Esegui questo comando in Cloud Shell per confermare che stai utilizzando il progetto corretto:

Una volta eseguita la connessione a Cloud Shell, dovresti vedere che il tuo account è già autenticato e il progetto è già impostato sul tuo ID progetto.

Nota:lo strumento a riga di comando gcloud è uno strumento a riga di comando potente e unificato disponibile in Google Cloud. È già installato in Cloud Shell. Noterai che supporta il completamento della scheda. Per ulteriori informazioni, consulta la panoramica dello strumento a riga di comando gcloud.

Esegui questo comando per verificare che sia in uso il progetto corretto.

gcloud config list project

Se vuoi utilizzare un progetto diverso da quello selezionato quando hai aperto Cloud Shell, puoi impostarne uno nuovo eseguendo:

gcloud config set project <PROJECT-ID>;

3. Configura un'istanza Cloud SQL per PostgreSQL con Query Insights abilitato

1. Dopo il lancio di Cloud Shell, puoi utilizzare la riga di comando per creare una nuova istanza Cloud SQL denominata my-instance, con Query Insights abilitato:

Nota:in questo codelab, attivi Query Insights tramite la riga di comando. ma può anche essere abilitato nella console dal menu Query Insights dell'istanza.

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

Ecco una breve spiegazione delle segnalazioni e del loro significato:

• Il flag --tier db-f1-micro specifica un tipo di macchina con risorse minime, poiché è a scopo di sviluppo e non hai bisogno di molte risorse per il codelab. Scopri di più sui livelli qui.
• Il flag --database-version=POSTGRES_12 crea un'istanza che sarà la versione 12 di PostgreSQL.
• Il flag --region=us-central specifica la regione in cui verrà creata l'istanza.
• Il flag --root-password=<PASSWORD> consente di specificare la password per l'utente postgres root. Assicurati di sostituire <PASSWORD> con una password di tua scelta.
• Il flag --insights-config-query-insights-enabled abilita Query Insights sulla tua istanza.
• Il flag --insights-config-record-application-tags consente di registrare i tag dell'applicazione. Scoprirai di più sui tag dell'applicazione nelle sezioni successive.
• Il flag --insights-config-record-client-address consente di registrare gli indirizzi IP client da Query Insights.

Ti potrebbe essere richiesto di abilitare l'API sqladmin.googleapis.com per il progetto. Se ti viene richiesto, seleziona y per abilitare l'API.

La creazione dell'istanza richiederà diversi minuti. Al termine dell'operazione, l'istanza sarà pronta per l'uso.

2. Ora crea un database che utilizzerai per l'app di esempio:

gcloud sql databases create votesdb --instance my-instance

Puoi anche accedere all'istanza e configurarla tramite la console Cloud.

3. Esegui questo comando per ottenere il nome della connessione dell'istanza nel formato PROJECT-ID:ZONE-ID:INSTANCE-ID. Lo utilizzerai in seguito per configurare l'app Node.js.

gcloud sql instances describe my-instance | grep connectionName

4. Crea un account di servizio da utilizzare con l'app

Gli account di servizio vengono utilizzati per concedere le autorizzazioni a utilizzare diversi servizi all'interno del progetto Google Cloud. Per questo codelab, te ne serve una per concedere l'autorizzazione al proxy Cloud SQL per connettersi alla tua istanza Cloud SQL.

Crea un account di servizio nella console

1. Vai alla pagina degli account di servizio IAM e fai clic sul pulsante nella parte superiore della pagina.
2. Assegna al tuo account di servizio un nome e un ID univoci e fai clic su CREA.
3. Nella pagina successiva, fai clic sul menu a discesa Seleziona un ruolo. Filtra per "Cloud SQL" e seleziona il ruolo Client Cloud SQL. Fai clic su CONTINUA, quindi su FINE.
4. Una volta creato l'account di servizio, fai clic sui tre puntini in Azioni per il tuo nuovo account di servizio e scegli Gestisci chiavi. Nella pagina successiva, seleziona AGGIUNGI CHIAVE, quindi Crea nuova chiave. Viene selezionato JSON; mantenere quella predefinita e fai clic su CREA. Verrà scaricato un file di chiave privata .json. Fai clic su CHIUDI.
5. In Cloud Shell, fai clic sui tre puntini per aprire il menu Altro e scegli Carica file. Vai al file .json che hai scaricato sul tuo computer locale e selezionalo. Il file .json verrà caricato nella home directory di Cloud Shell.

5. Installa e avvia il proxy Cloud SQL

Utilizzerai il proxy Cloud SQL per la comunicazione tra l'applicazione e l'istanza del database.

1. Scarica il proxy Cloud SQL. In Cloud Shell puoi eseguire:

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

2. Esegui il proxy come segue dopo aver sostituito <INSTANCE_CONNECTION_NAME> con il nome della connessione dell'istanza che hai copiato dalla pagina Panoramica dell'istanza Cloud SQL.

./cloud_sql_proxy -instances=<INSTANCE_CONNECTION_NAME>=tcp:5432 &

Se l'operazione riesce, dovresti vedere alcune righe di output, che terminano con un messaggio Ready for new connections.

6. Clona e testa l'app in locale

1. Clona il repository per l'applicazione di esempio e installa i pacchetti necessari per eseguire l'app.

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

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

npm install

2. Imposta le seguenti variabili di ambiente:

export INSTANCE_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. Avvia l'app di esempio.

npm start

4. Fai clic su Anteprima web in Cloud Shell, quindi seleziona Anteprima sulla porta 8080.

Dovresti vedere l'app per la votazione Schede e Spazi come mostrato qui nel tuo browser:

5. Fai clic sui pulsanti per assegnare dei voti e salvare alcuni dati nel database.

7. Aggiungi una pagina per visualizzare tutti i voti

Poiché questa applicazione di esempio è molto semplice, aggiungerai un'altra pagina che mostra tutti i voti. Il motivo principale è che avrai a disposizione più dati da esaminare quando utilizzerai Query Insights in un secondo momento.

1. Inserisci Ctrl+c in Cloud Shell per arrestare l'app di esempio.
2. In Cloud Shell, fai clic sul pulsante per avviare l'editor di Cloud Shell.
3. In Esplora file, trova nodejs-docs-samples/cloud-sql/postgres/knex/server.js e fai clic sul file per caricare il file server.js nell'editor.

Aggiungi il seguente codice dopo il punto in cui è definita la funzione 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. Aggiungi il seguente codice per la route '/getAllVotes' nel punto in cui sono definite le altre route:

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. Crea un nuovo file nella directory nodejs-docs-samples/cloud-sql/postgres/knex/views denominato allvotes.pug. Incolla il seguente codice:

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. Fai clic sul pulsante per tornare a Cloud Shell ed eseguire:

npm start

7. Apri l'app da Anteprima web per assicurarti che funzioni. Aggiungi /getAllVotes all'URL nel browser per visualizzare la nuova pagina aggiunta.

8. Abilita commentatore SQL nell'app

Ora installerai e abiliterai SQL Commenter, una libreria open source che consente agli ORM di arricchire le istruzioni SQL con commenti prima dell'esecuzione. SQLcommenter supporta diversi ORM e framework, tra cui quello utilizzato dall'app di esempio: Knex.js. Query Insights utilizza le informazioni contenute in questi commenti per offrire una visione incentrata sull'applicazione delle prestazioni del database e identificare il codice dell'applicazione che causa problemi. L'overhead delle prestazioni dovrebbe essere basso. Consulta la documentazione Query Insights.

1. Inserisci Ctrl+c in Cloud Shell per arrestare l'app di esempio.
2. Esegui questo comando per installare i pacchetti necessari per SQLcommenter:

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

3. In Cloud Shell, fai clic sul pulsante per avviare l'editor di Cloud Shell.
4. In Esplora file, trova nodejs-docs-samples/cloud-sql/postgres/knex/server.js e fai clic sul file per caricare il file server.js nell'editor.
5. Cerca questo codice nel file:

const process = require('process');

Aggiungi il seguente codice sotto la notifica:

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

6. Cerca questo codice nel file:

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

Aggiungi il seguente codice sotto la notifica:

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

Al termine, il codice dovrebbe avere un aspetto simile al seguente:

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

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

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

// Automatically parse request body as form data.
app.use(express.urlencoded({extended: false}));
// This middleware is available in Express v4.16.0 onwards
app.use(express.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. Fai clic sul pulsante per tornare a Cloud Shell ed eseguire:

npm start

8. Nell'applicazione Tabs vs Space, fai clic sui pulsanti per assegnare altri voti e aggiungere altri dati al database.

9. Utilizza gli insight per visualizzare le prestazioni delle query e il tracciamento end-to-end

La dashboard di Query Insights aiuta a risolvere i problemi relativi alle query di Cloud SQL per cercare problemi di prestazioni. Per accedere a Insights, seleziona Query Insights nel menu di navigazione a sinistra per la tua istanza Cloud SQL.

Carico database - Grafico di tutte le query

La dashboard di primo livello Query Insights mostra il grafico Carico database - Tutte le query.

Il grafico contiene informazioni su capacità della CPU, CPU e attesa di CPU, attesa I/O e attesa blocco. Puoi ottenere ulteriori informazioni sul significato di queste metriche e su dove sono archiviate le metriche, oltre a consultare alcuni esempi di come questo grafico in relazione alle query problematiche nella documentazione. Nel caso di questa applicazione di esempio, il carico delle query del database è basso, quindi non ci sono grandi picchi nel grafico.

Quali query sono responsabili del maggior carico?

Sotto il grafico, viene visualizzata la tabella QUERIES che contiene le query normalizzate per l'intervallo di tempo selezionato. Le query nella tabella sono ordinate in base al tempo totale di esecuzione.

Puoi fare clic su una singola query per visualizzare informazioni dettagliate sulla query, come il carico del database per questa query specifica, la latenza della query, gli esempi di piani di query e gli utenti principali. Se un'applicazione viene creata utilizzando un file ORM, come nel caso dell'applicazione di esempio, potresti non sapere quale parte dell'applicazione è responsabile di una determinata query. La sezione Tag principali può aiutarti a scoprirlo.

Dove ha origine il carico delle query nell'applicazione?

Passa dalla tabella QUERY alla tabella TAG per visualizzare un elenco di query codificate in base alla logica di business, in modo da avere una visione più incentrata sull'applicazione.

Nella tabella TAGS puoi vedere il carico del database suddiviso in base alla route che ha generato il carico. Nello screenshot riportato sopra, puoi vedere che la route '/getAllVotes' ha un tempo di esecuzione medio più elevato e in media vengono restituite più righe. Sebbene il tempo di esecuzione indicato nella tabella non sia problematico in questo caso, facciamo comunque clic sulla riga relativa a '/getAllVotes' per esaminare i dati in modo più dettagliato.

Perché le query vengono eseguite lentamente?

Fai clic sul punto nel grafico Esempi di piani di query per visualizzare un piano di query.

I piani di query mostrano come PostgreSQL esegue una query sotto le coperte, semplificando la determinazione se ci sono operazioni che comportano un rallentamento.

Quale codice dell'applicazione contribuisce alla lentezza?

Query Insights fornisce inoltre la visualizzazione contestuale del tracciamento end-to-end, che può essere utile per svolgere ulteriori indagini sulle parti di un'applicazione che generano query lente.

Fai clic sulla scheda FINE A FINE per visualizzare una traccia nel contesto.

Nota: per saperne di più su come utilizzare e interpretare i piani di query e il tracciamento end-to-end, consulta la documentazione.

10. Libera spazio e scopri di più

Hai imparato a utilizzare Query Insights per monitorare e analizzare le prestazioni delle query con un'app Node.js e un database PostgreSQL di Cloud SQL.

Pulizia

Se non vuoi mantenere in esecuzione l'istanza Cloud SQL, puoi eliminarla ora.

gcloud sql instances delete my-instance

Scopri di più

• Utilizzo della documentazione di Query Insights
• Abilita il tagging delle query con Sqlcommenter per comprendere l'impatto dell'applicazione sulle prestazioni del database
• Documentazione di SQL Commenter
• Repository GitHub di SQL Commenter