Questa pagina è stata tradotta dall'API Cloud Translation.

Profilazione delle applicazioni Node.js

Questa pagina descrive come modificare l'applicazione Node.js per acquisire i dati di profilazione e inviarli al tuo progetto Google Cloud. Per informazioni generali sulla profilazione, vedi Concetti di profilazione.

Tipi di profilo per Node.js:

Heap
Tempo totale di esecuzione

Versioni del linguaggio Node.js supportate:

Node.js 14 o versioni successive
Per le norme di rilascio di Node.js, consulta la pianificazione dei rilasci.

Versioni dell'agente di profilazione supportate:

È supportata la versione più recente dell'agente. In generale, le release più vecchie di un anno non sono supportate. Ti consigliamo di utilizzare la versione dell'agente rilasciata più di recente.

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 di configurazione specifiche per i kernel Linux Alpine, vedi Esecuzione su Linux Alpine.

Ambienti supportati:

Compute Engine
Google Kubernetes Engine (GKE)
Ambiente flessibile di App Engine
Ambiente standard di App Engine
Al di fuori di Google Cloud (per informazioni sui requisiti di configurazione aggiuntivi, vedi Profilazione delle applicazioni in esecuzione al di fuori di Google Cloud).

Attivazione 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

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

Esegui questo comando:

gcloud services enable cloudprofiler.googleapis.com

Per ulteriori informazioni, vedi gcloud services.

Console Google Cloud

Enable the required API.
Enable the API
Se viene visualizzato il messaggio API abilitata, l'API è già abilitata. In caso contrario, fai clic sul pulsante Attiva.

Concedi ruolo IAM al account di servizio

Se stai eseguendo il deployment dell'applicazione sulle risorse Google Cloud e se utilizzi il account di servizio predefinito e non hai modificato le concessioni di ruolo a questo account di servizio, puoi saltare questa sezione.

Se esegui una delle seguenti operazioni, devi concedere all'account di servizio il ruolo IAM Agente Cloud Profiler (roles/cloudprofiler.agent):

Stai utilizzando il account di servizio predefinito, ma hai modificato le concessioni di ruolo.
Stai utilizzando un account di servizio creato dall'utente.
Stai utilizzando Workload Identity, concedi il ruolo Agente Cloud Profiler al account di servizio Kubernetes.

Puoi concedere un ruolo IAM a un account di servizio utilizzando la consoleGoogle Cloud o Google Cloud CLI. Ad esempio, potresti utilizzare il comando gcloud projects add-iam-policy-binding:

gcloud projects add-iam-policy-binding GCP_PROJECT_ID \
    --member serviceAccount:MY_SVC_ACCT_ID@GCP_PROJECT_ID.iam.gserviceaccount.com \
    --role roles/cloudprofiler.agent

Prima di utilizzare il comando precedente, sostituisci quanto segue:

GCP_PROJECT_ID: il tuo ID progetto.
MY_SVC_ACCT_ID: il nome del account di servizio.

Per informazioni dettagliate, vedi Gestire l'accesso a progetti, cartelle e organizzazioni.

Utilizzo di Cloud Profiler

In tutti gli ambienti supportati, utilizzi Profiler installando il pacchetto @google-cloud/profiler, aggiungendo un'istruzione require all'applicazione e poi eseguendo il deployment dell'applicazione nel solito modo.

Prima di installare `@google-cloud/profiler`

Il pacchetto @google-cloud/profiler dipende da un modulo integrato. I binari precompilati per questo modulo integrato sono disponibili per Linux e Alpine Linux per Node 14 e 16. Non sono richieste dipendenze aggiuntive. @google-cloud/profiler utilizza node-pre-gyp per determinare quale binario precompilato installare.

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

Installazione

Per installare l'ultima versione di Cloud Profiler:

    npm install @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:

Installa l'ultima versione di Cloud Profiler:
```
npm install @google-cloud/profiler
```
Modifica il codice require dell'applicazione per creare un oggetto serviceContext che assegna a service il nome del servizio di cui viene eseguito il profiling. (Facoltativo) Puoi assegnare a version la versione del servizio di cui viene eseguito il profiling. Per ulteriori informazioni su queste opzioni di configurazione, consulta Argomenti relativi al nome e alla versione del servizio:
```
require('@google-cloud/profiler').start({
  serviceContext: {
    service: 'your-service',
    version: '1.0.0',
  },
});
```

GKE

Per GKE, segui questi passaggi:

Modifica il Dockerfile per installare il pacchetto Profiler:
```
FROM node:10
...
RUN npm install @google-cloud/profiler
```
Modifica il codice require dell'applicazione per creare un oggetto serviceContext che assegna a service il nome del servizio di cui viene eseguito il profiling. (Facoltativo) Puoi assegnare a version la versione del servizio di cui viene eseguito il profiling. Per ulteriori informazioni su queste opzioni di configurazione, consulta Argomenti relativi al nome e alla versione del servizio:
```
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 devi specificarli. Pertanto, non è necessario creare un oggetto serviceContext.

Analisi dei dati

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

Nella console Google Cloud , vai alla pagina Profiler:

Vai a Profiler

Puoi trovare questa pagina anche utilizzando la barra di ricerca.

Argomenti del nome e della versione del servizio

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

Il nome del servizio consente a Profiler di raccogliere dati di profilazione per tutte le repliche del servizio. Il servizio di profilazione garantisce una velocità di raccolta di un profilo al minuto, in media, per ogni nome di servizio in ogni combinazione di versioni e zone del 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 più elevato.

Quando selezioni un nome 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 applicazione. È più importante se la tua applicazione viene eseguita come un insieme di microservizi, ad esempio.
Assicurati di non utilizzare valori specifici del processo, come un ID processo, nella stringa service-name.
La stringa service-name deve corrispondere a questa espressione regolare:

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

Una buona linea guida è 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 utilizzato per contrassegnare le diverse versioni dei tuoi servizi durante la loro implementazione. L'interfaccia utente di Profiler ti consente di filtrare i dati in base alla versione del servizio, in modo da confrontare il rendimento 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 in genere assomigliano a numeri di versione, ad esempio, 1.0.0 o 2.1.2.

Logging dell'agente

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

0: disattiva tutti i log dell'agente.
1: attiva la registrazione degli errori.
2: attiva la registrazione degli avvisi (impostazione predefinita).
3: attiva la registrazione delle informazioni.
4: attiva la registrazione di 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 con il seguente errore, significa che nel Dockerfile mancano alcune dipendenze di build:

ERR! stack Error: not found: make

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

RUN apk add python3 g++ make

Errore di autenticazione

Se utilizzi immagini Docker eseguite con Linux Alpine (ad esempio golang:alpine o semplicemente 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 aver attivato la registrazione dell'agente.

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

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

Dopodiché, devi ricompilare e ridistribuire l'applicazione.

Problemi noti

L'agente di profilazione per Node.js interferisce con l'uscita normale del programma; possono essere necessarie fino a un'ora prima che il programma esca dopo il completamento di tutte le attività. Quando emetti un SIGINT, ad esempio utilizzando Ctrl-C, il processo termina normalmente.