Configurazione di Cloud Trace per Node.js

Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.

Puoi abilitare Cloud Trace per le applicazioni Node.js utilizzando la libreria Cloud Trace per Node.js.

Installare la libreria client

  1. Prima di installare la libreria Cloud Trace per Node.js, assicurati di aver preparato il tuo ambiente per lo sviluppo Node.js.

  2. Per installare la libreria Cloud Trace per Node.js, utilizza npm:

    npm install --save @google-cloud/trace-agent
  3. Importa la libreria Cloud Trace per Node.js nella parte superiore dello script o del punto di ingresso principale dell'applicazione prima di qualsiasi altro codice:

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

Per ulteriori informazioni o per segnalare problemi con la libreria di Cloud Trace per Node.js, consulta il cloud-trace-nodejs repository GitHub dell'agente.

Configurazione della libreria client

Puoi personalizzare il comportamento della libreria di Cloud Trace per Node.js. Consulta la configurazione della libreria su GitHub per un elenco di opzioni di configurazione che puoi trasmettere al metodo start della libreria, utilizzando un oggetto options.

L'esempio seguente mostra come specificare l'ID progetto Google Cloud e impostare il percorso del file delle credenziali. Queste due istruzioni sono facoltative quando utilizzi Google Cloud:

require('@google-cloud/trace-agent').start({
  projectId: 'your-project-id',
  keyFilename: '/path/to/key.json',
});

Se utilizzi l'infrastruttura Google Cloud, non devi impostare projectId sul tuo ID progetto Google Cloud. Se non imposti questo campo, la libreria client per Node.js raccoglie automaticamente questi dati da un server di metadati Google Cloud.

Se non utilizzi l'infrastruttura Google Cloud, devi fornire il tuo ID progetto Google Cloud alla tua applicazione.

Indipendentemente dalla tua infrastruttura, per Node.js, se non imposti esplicitamente l'ID progetto Google Cloud, la libreria cloud-trace-nodejs determina automaticamente se la variabile di ambiente GCLOUD_PROJECT è impostata e, in questo caso, la libreria utilizza il valore GCLOUD_PROJECT come ID progetto Google Cloud. Per maggiori informazioni sul file di rilevamento, vai alla pagina cloud-trace-nodejs/src/index. Per impostare la variabile di ambiente:

Linux o macOS

export GCLOUD_PROJECT=your-project-id

Windows

set GCLOUD_PROJECT=your-project-id

PowerShell:

$env:GCLOUD_PROJECT="your-project-id"

Configura la tua piattaforma

Puoi utilizzare Cloud Trace su Google Cloud e altre piattaforme.

Esecuzione in Google Cloud

Quando la tua applicazione è in esecuzione su Google Cloud, non devi fornire le credenziali di autenticazione sotto forma di account di servizio alla libreria client. Tuttavia, devi assicurarti che l'ambito di accesso all'API Cloud Trace sia abilitato nella tua piattaforma Google Cloud.

Per un elenco degli ambienti Google Cloud supportati, consulta la pagina Assistenza per l'ambiente.

Per le seguenti configurazioni, le impostazioni predefinite dell'ambito di accesso abilitano l'API Cloud Trace:

  • Ambiente flessibile di App Engine
  • Ambiente standard di App Engine

  • Google Kubernetes Engine (GKE)

  • Compute Engine

  • Cloud Run

Se utilizzi ambiti di accesso personalizzati, devi assicurarti che l'ambito di accesso all'API Cloud Trace sia abilitato:

  • Per informazioni su come configurare gli ambiti di accesso per il tuo ambiente utilizzando Google Cloud Console, consulta Configurazione del progetto Google Cloud.

  • Per gli utenti gcloud, specifica gli ambiti di accesso utilizzando il flag --scopes e includi l'ambito di accesso API Cloud Trace trace.append. Ad esempio, per creare un cluster GKE con solo l'API Cloud Trace abilitata, segui questi passaggi:

    gcloud container clusters create example-cluster-name --scopes=https://www.googleapis.com/auth/trace.append

Esecuzione locale e altrove

Se la tua applicazione viene eseguita al di fuori di Google Cloud, devi fornire le credenziali di autenticazione sotto forma di account di servizio alla libreria client. L'account di servizio deve contenere il ruolo di agente Cloud Trace. Per le istruzioni, vedi Creare un account di servizio.

Le librerie client di Google Cloud utilizzano le credenziali predefinite dell'applicazione per trovare le credenziali dell'applicazione.

Per fornire queste credenziali, puoi utilizzare uno dei tre metodi seguenti:

  • Esegui gcloud auth application-default login

  • Posiziona l'account di servizio in un percorso predefinito per il tuo sistema operativo. Di seguito sono elencati i percorsi predefiniti per Windows e Linux:

    • Windows: %APPDATA%/gcloud/application_default_credentials.json

    • Linux: $HOME/.config/gcloud/application_default_credentials.json

  • Imposta la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS sul percorso del tuo account di servizio:

Linux/macOS

    export GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

Windows

    set GOOGLE_APPLICATION_CREDENTIALS=path-to-your-service-accounts-private-key

PowerShell:

    $env:GOOGLE_APPLICATION_CREDENTIALS="path-to-your-service-accounts-private-key"

Applicazione di esempio

if (process.env.NODE_ENV === 'production') {
  require('@google-cloud/trace-agent').start();
}

const express = require('express');
const got = require('got');

const app = express();
const DISCOVERY_URL = 'https://www.googleapis.com/discovery/v1/apis';

// This incoming HTTP request should be captured by Trace
app.get('/', async (req, res) => {
  // This outgoing HTTP request should be captured by Trace
  try {
    const {body} = await got(DISCOVERY_URL, {responseType: 'json'});
    const names = body.items.map(item => item.name);
    res.status(200).send(names.join('\n')).end();
  } catch (err) {
    console.error(err);
    res.status(500).end();
  }
});

// Start the server
const PORT = process.env.PORT || 8080;
app.listen(PORT, () => {
  console.log(`App listening on port ${PORT}`);
  console.log('Press Ctrl+C to quit.');
});

Visualizzazione delle tracce

Dopo il deployment, puoi visualizzare le tracce in Visualizzatore Trace di Google Cloud Console.

Vai alla pagina Visualizzatore tracce

Risolvere i problemi

Per informazioni sulla risoluzione dei problemi con Cloud Trace, consulta la pagina per la risoluzione dei problemi.

Risorse