Profilazione delle applicazioni Node.js

In questa pagina viene descritto come modificare l'applicazione Node.js per acquisire i dati di profilazione e inviarli al progetto Google Cloud. Per informazioni generali sulla profilazione, consulta Concetti di profilazione.

Tipi di profilo per Node.js:

  • Heap
  • Tempo totale di esecuzione

Versioni del linguaggio Node.js supportate:

Versioni dell'agente di profilazione supportate:

  • È supportata la release più recente dell'agente. In genere, le release che risalgono a più di un anno fa non sono supportate. Ti consigliamo di utilizzare la versione rilasciata più recente dell'agente.

Sistemi operativi supportati:

  • Linux. La profilazione delle applicazioni Node.js è supportata per i kernel Linux la cui libreria C standard è implementata con glibc o con musl. Per informazioni sulla configurazione specifiche per i kernel Alpine di Linux, consulta Esecuzione su Linux Alpine.

Ambienti supportati:

Abilitazione dell'API Profiler

Prima di utilizzare l'agente di profilazione, assicurati che l'API Profiler sottostante sia abilitata. Puoi controllare lo stato dell'API e abilitarla, se necessario, utilizzando Google Cloud CLI o la console Google Cloud:

Interfaccia a riga di comando gcloud

  1. Se non hai già installato Google Cloud CLI sulla tua workstation, consulta la documentazione di Google Cloud CLI.

  2. Esegui questo comando:

    gcloud services enable cloudprofiler.googleapis.com

Per maggiori informazioni, consulta gcloud services.

Console Google Cloud

  1. Nel pannello di navigazione della console Google Cloud, seleziona API e servizi, fai clic su Abilita API e servizi e poi abilita l'API Cloud Profiler:

    Vai alle impostazioni dell'API Profiler

  2. Se viene visualizzato API abilitata, significa che l'API è già abilitata. In caso contrario, fai clic sul pulsante Attiva.

Utilizzo di Cloud Profiler

In tutti gli ambienti supportati, puoi utilizzare Profiler installando il pacchetto @google-cloud/profiler, aggiungendo un'istruzione require all'applicazione ed eseguendo il deployment dell'applicazione come di consueto.

Prima di installare @google-cloud/profiler

Il pacchetto @google-cloud/profiler dipende da un modulo nativo. I file binari predefiniti per questo modulo nativo sono disponibili per Linux e Alpine Linux per i nodi 14 e 16. Non sono necessarie ulteriori dipendenze. @google-cloud/profiler usa node-pre-gyp per determinare quale programma binario predefinito installare.

Quando utilizzi @google-cloud/profiler in altri ambienti che non dispongono di programmi binari predefiniti, il modulo node-gyp viene utilizzato per creare programmi binari. Per informazioni sulle dipendenze necessarie per creare file binari con node-gyp, consulta la documentazione di installazione di node-gyp.

Installazione

Per installare la versione più recente di Cloud Profiler, segui questi passaggi:

    npm install --save @google-cloud/profiler

Se utilizzi anche l'agente Trace, quando modifichi l'applicazione, importa il pacchetto Profiler dopo il pacchetto dell'agente Trace (@google-cloud/trace-agent).

Compute Engine

Per Compute Engine, segui questi passaggi:

  1. Installa la versione più recente di Cloud Profiler:

    npm install --save @google-cloud/profiler

  2. Modifica il codice require della tua applicazione per creare un oggetto serviceContext che assegni a service il nome del servizio che viene profilato. Facoltativamente, puoi assegnare a version la versione del servizio che stai profilando. Vedi Argomenti della versione e del nome del servizio per ulteriori informazioni su queste opzioni di configurazione:

    require('@google-cloud/profiler').start({
  serviceContext: {
    service: 'your-service',
    version: '1.0.0',
  },
});

GKE

Per GKE, segui questi passaggi:

  1. Modifica il tuo Dockerfile per installare il pacchetto Profiler:

    FROM node:10
...
RUN npm install @google-cloud/profiler

  2. Modifica il codice require della tua applicazione per creare un oggetto serviceContext che assegni a service il nome del servizio che viene profilato. Facoltativamente, puoi assegnare a version la versione del servizio che stai profilando. Vedi Argomenti della versione e del nome del servizio per ulteriori informazioni su queste opzioni di configurazione:

    require('@google-cloud/profiler').start({
  serviceContext: {
    service: 'your-service',
    version: '1.0.0',
  },
});

App Engine

Per l'ambiente flessibile di App Engine e per l'ambiente standard di App Engine, il codice require è simile al seguente:

require('@google-cloud/profiler').start();

In App Engine, i parametri service e version derivano dall'ambiente, quindi non è necessario specificarli. Pertanto, non devi creare un oggetto serviceContext.

Analisi dei dati

Dopo che Profiler ha raccolto i dati, puoi visualizzarli e analizzarli utilizzando l'interfaccia di Profiler.

Nel pannello di navigazione della console Google Cloud, seleziona Profiler:

Vai a Profiler

Argomenti della versione e del nome del servizio

Quando carichi l'agente Profiler, devi specificare un argomento service-name e un argomento service-version facoltativo per configurarlo.

Il nome del servizio consente a Profiler di raccogliere i dati di profilazione per tutte le repliche di quel servizio. Il servizio profiler garantisce una frequenza di raccolta di un profilo al minuto, in media, per ciascun nome di servizio in ogni combinazione di versioni e zone di servizio.

Ad esempio, se hai un servizio con due versioni in esecuzione su repliche in tre zone, il profiler creerà una media di 6 profili al minuto per quel servizio.

Se utilizzi nomi di servizio diversi per le repliche, il servizio verrà profilato più spesso del necessario, con un overhead corrispondentemente maggiore.

Quando selezioni il nome di un servizio:

  • Scegli un nome che rappresenti chiaramente il servizio nell'architettura dell'applicazione. La scelta del nome del servizio è meno importante se esegui un solo servizio o una singola applicazione. Ad esempio, è più importante se l'applicazione viene eseguita come un insieme di micro-servizi.

  • Assicurati di non utilizzare valori specifici del processo, come un ID processo, nella stringa del nome del servizio.

  • La stringa del nome del servizio deve corrispondere alla seguente espressione regolare:

    ^[a-z0-9]([-a-z0-9_.]{0,253}[a-z0-9])?$

Una buona linea guida è quella di utilizzare una stringa statica come imageproc-service come nome del servizio.

La versione del servizio è facoltativa. Se specifichi la versione del servizio, Profiler può aggregare le informazioni di profilazione da più istanze e visualizzarle correttamente. Può essere usata per contrassegnare le diverse versioni dei servizi man mano che ne viene eseguito il deployment. L'interfaccia utente di Profiler ti consente di filtrare i dati in base alla versione del servizio, in modo da confrontare le prestazioni delle versioni precedenti e più recenti del codice.

Il valore dell'argomento service-version è una stringa in formato libero, ma i valori per questo argomento solitamente sono come numeri di versione, ad esempio 1.0.0 o 2.1.2.

Logging degli agenti

L'agente di profilazione può segnalare informazioni di logging. Per abilitare il logging, imposta l'opzione logLevel all'avvio dell'agente. I valori logLevel supportati sono:

  • 0: disabilita il logging degli agenti.
  • 1: consente il logging degli errori.
  • 2: attiva il logging degli avvisi (impostazione predefinita).
  • 3: consente il logging delle informazioni.
  • 4: attiva il logging del debug.

Imposta il valore logLevel nello stesso oggetto che fornisce il contesto del servizio:

require('@google-cloud/profiler').start({
    serviceContext: { ... }
    logLevel:       3
});

Esecuzione con Linux Alpine

L'agente di profilazione Node.js per Linux Alpine è supportato solo per le configurazioni di Google Kubernetes Engine.

Errore di compilazione

Se esegui npm install e la build non riesce a generare l'errore seguente, nel Dockerfile mancano alcune dipendenze di build:

ERR! stack Error: not found: make

Per risolvere il problema, aggiungi la seguente istruzione alla fase di creazione del Dockerfile:

RUN apk add python3 g++ make

Errore di autenticazione

Se utilizzi immagini Docker eseguite con Linux Alpine (ad esempio golang:alpine o solo alpine), potresti visualizzare il seguente errore di autenticazione:

connection error: desc = "transport: authentication handshake failed: x509: failed to load system roots and no roots provided"

Tieni presente che, per visualizzare l'errore, devi avere abilitato il logging degli agenti.

L'errore indica che nelle immagini Docker con Linux Alpine non sono installati i certificati SSL radice per impostazione predefinita. Questi certificati sono necessari affinché l'agente di profilazione comunichi con l'API Profiler. Per risolvere questo errore, aggiungi il comando apk seguente al tuo Dockerfile:

FROM alpine
...
RUN apk add --no-cache ca-certificates

Poi devi ricreare l'applicazione ed eseguirne nuovamente il deployment.

Problemi noti

L'agente di profilazione per Node.js interferisce con la normale uscita del programma; può essere necessaria fino a un'ora prima che il programma venga chiuso dopo il completamento di tutte le attività. Quando emetti un SIGINT, ad esempio utilizzando Ctrl-C, il processo viene arrestato automaticamente.

Passaggi successivi