Configurazione di Cloud Trace per Node.js

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

Installazione della libreria client

  1. Prima di installare la libreria Cloud Trace per Node.js, assicurati di aver preparato l'ambiente per lo sviluppo in 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 principale o del punto di ingresso dell'applicazione prima di qualsiasi altro codice:

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

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

Configurazione della libreria client

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

L'esempio seguente mostra la specifica dell'ID progetto Google Cloud e l'impostazione del percorso del file delle credenziali. Queste due istruzioni sono facoltative quando esegui l'esecuzione su Google Cloud:

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

Se è in esecuzione sull'infrastruttura Google Cloud, non è necessario 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 metadati di Google Cloud.

Se non è in esecuzione sull'infrastruttura Google Cloud, devi fornire il tuo ID progetto Google Cloud all'applicazione.

Indipendentemente dall'infrastruttura, per Node.js, quando non imposti esplicitamente l'ID progetto Google Cloud, la libreria cloud-trace-nodejs determina automaticamente se è impostata la variabile di ambiente GCLOUD_PROJECT e, in questo caso, la libreria utilizza il valore GCLOUD_PROJECT come ID progetto Google Cloud. Per maggiori informazioni sul file di rilevamento, vai a 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.

In esecuzione su Google Cloud

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

Per un elenco degli ambienti Google Cloud supportati, consulta la pagina relativa all'assistenza per gli ambienti.

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

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 la console Google Cloud, 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 all'Cloud Trace API trace.append. Ad esempio, per creare un cluster GKE in cui è abilitata solo l'Cloud Trace API:

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

Esecuzione in locale e altrove

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

Le librerie client di Google Cloud utilizzano le Credenziali predefinite dell'applicazione (ADC) per trovare le credenziali della tua applicazione.

Puoi fornire queste credenziali in uno dei tre modi seguenti:

  • Esegui gcloud auth application-default login

  • Inserisci 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 al 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.');
});

Visualizza tracce

Nel pannello di navigazione della console Google Cloud, seleziona Trace e poi Trace Explorer:

Vai a Trace Explorer

Risoluzione dei problemi

Per informazioni sulla risoluzione dei problemi relativi a Cloud Trace, vai alla pagina Risoluzione dei problemi.

Risorse