Cloud Trace für Node.js einrichten

Sie können Cloud Trace für Node.js-Anwendungen mithilfe der Cloud Trace-Bibliothek für Node.js aktivieren.

Clientbibliothek installieren

  1. Bevor Sie die Cloud Trace-Bibliothek für Node.js installieren, müssen Sie Ihre Umgebung für die Node.js-Entwicklung vorbereitet haben.

  2. Mit npm installieren Sie die Cloud Trace-Bibliothek für Node.js:

    npm install --save @google-cloud/trace-agent

  3. Importieren Sie die Cloud Trace-Bibliothek für Node.js am Anfang des Hauptskripts oder des Einstiegspunkt Ihrer Anwendung vor jedem anderen Code:

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

Weitere Informationen finden Sie im cloud-trace-nodejs-GitHub-Repository des Agents. Hier können Sie auch Probleme mit der Cloud Trace-Bibliothek für Node.js melden.

Clientbibliothek konfigurieren

Sie können das Verhalten der Cloud Trace-Bibliothek für Node.js anpassen. Eine Liste der Konfigurationsoptionen, die Sie mithilfe eines options-Objekts an die Methode start der Bibliothek übergeben können, finden Sie unter Konfiguration der Bibliothek auf GitHub.

Im folgenden Beispiel wird gezeigt, wie die Google Cloud-Projekt-ID angegeben und der Pfad zu Ihrer Anmeldedatendatei festgelegt wird. Diese beiden Anweisungen sind optional, wenn Sie in Google Cloud arbeiten:

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

Wenn Sie in der Google Cloud-Infrastruktur arbeiten, müssen Sie projectId nicht auf Ihre Google Cloud-Projekt-ID festlegen. Wenn Sie dieses Feld nicht festlegen, erfasst die Clientbibliothek für Node.js diese Daten automatisch von einem Google Cloud-Metadatenserver.

Wenn Sie nicht die Google Cloud-Infrastruktur ausführen, müssen Sie Ihre Google Cloud-Projekt-ID für Ihre Anwendung angeben.

Unabhängig von Ihrer Infrastruktur bestimmt die cloud-trace-nodejs-Bibliothek für Node.js automatisch, ob die Umgebungsvariable GCLOUD_PROJECT festgelegt ist. Ist dies der Fall, verwendet die Bibliothek den Wert GCLOUD_PROJECT als Ihre Google Cloud-Projekt-ID. Weitere Informationen zur Discovery-Datei finden Sie unter cloud-trace-nodejs/src/index. So legen Sie die Umgebungsvariable fest:

Linux oder macOS

export GCLOUD_PROJECT=your-project-id

Windows

set GCLOUD_PROJECT=your-project-id

PowerShell:

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

Ihre Plattform konfigurieren

Sie können Cloud Trace in Google Cloud und auf anderen Plattformen verwenden.

In Google Cloud ausführen

Wenn Ihre Anwendung in Google Cloud ausgeführt wird, müssen Sie der Clientbibliothek keine Anmeldedaten in Form eines Dienstkontos bereitstellen. Sie müssen jedoch darauf achten, dass auf Ihrer Google Cloud Platform der Cloud Trace API-Zugriffsbereich aktiviert ist.

Für die folgenden Konfigurationen wird die Cloud Trace API über die Standardeinstellungen für den Zugriffsbereich aktiviert:

  • Flexible App Engine-Umgebung

  • App Engine-Standardumgebung

  • Google Kubernetes Engine (GKE)

  • Compute Engine

Wenn Sie benutzerdefinierte Zugriffsbereiche verwenden, muss der Zugriffsbereich der Cloud Trace API aktiviert sein. Geben Sie für gcloud-Nutzer Zugriffsbereiche mit dem Flag --scopes an und fügen Sie den Cloud Trace API-Zugriffsbereich trace.append hinzu. So erstellen Sie beispielsweise einen GKE-Cluster, für den nur die Cloud Trace API aktiviert ist:

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

Lokal und extern ausführen

Wenn Ihre Anwendung außerhalb von Google Cloud ausgeführt wird, müssen Sie Authentifizierungsdaten in Form eines Dienstkontos für die Clientbibliothek angeben. Das Dienstkonto muss die Rolle Cloud Trace Agent enthalten. Informationen dazu finden Sie unter Dienstkonto erstellen.

Google Cloud-Clientbibliotheken verwenden Standardanmeldedaten für Anwendungen, um die Anmeldedaten Ihrer Anwendung zu finden. Sie geben diese Anmeldedaten an, indem Sie die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS festlegen:

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"

Beispielanwendung

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

Traces ansehen

Nach der Bereitstellung können Sie die Traces im Trace Viewer der Cloud Console anzeigen.

Trace-Anzeige öffnen

Fehlerbehebung

Informationen zur Behebung von Problemen mit Cloud Trace finden Sie auf der Seite zur Fehlerbehebung.

Ressourcen