Cloud Trace für Node.js einrichten

Sie können Cloud Trace für Node.js-Anwendungen mit 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. So installieren Sie die Cloud Trace-Bibliothek für Node.js mit npm:

    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 Node.js Trace-Bibliothek für Node.js anpassen. Die Konfiguration der Bibliothek auf GitHub enthält eine Liste der Konfigurationsoptionen, die Sie mit einem options-Objekt an die Methode start der Bibliothek übergeben können.

Das folgende Beispiel zeigt, wie Sie die Google Cloud-Projekt-ID angeben und den Pfad zu Ihrer Anmeldedatendatei festlegen. Diese beiden Anweisungen sind optional, wenn Sie Google Cloud ausführen:

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

Wenn Sie mit der Google Cloud-Infrastruktur arbeiten, müssen Sie projectId nicht auf Ihre Google Cloud-Projekt-ID festsetzen. 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.

Wenn Sie die Google Cloud-Projekt-ID nicht explizit festlegen, ermittelt die Python-Bibliothek cloud-trace-nodejs unabhängig von Ihrer Infrastruktur automatisch, ob die Umgebungsvariable GCLOUD_PROJECT ist. Ist dies der Fall, verwendet die Bibliothek den Wert von 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"

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 für die Clientbibliothek keine Anmeldedaten zur Authentifizierung in der Clientbibliothek angeben. Für die Google Cloud Platform muss jedoch der Zugriffsbereich der Cloud Trace API aktiviert sein.

Eine Liste der unterstützten Google Cloud-Umgebungen finden Sie unter Umgebungsunterstützung.

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

  • Cloud Run

Wenn Sie benutzerdefinierte Zugriffsbereiche verwenden, muss der Zugriffsbereich der Cloud Trace API aktiviert sein:

  • Informationen zum Konfigurieren der Zugriffsbereiche für Ihre Umgebung mit der Google Cloud Console finden Sie unter Google Cloud-Projekt konfigurieren.

  • Geben Sie für gcloud-Nutzer mithilfe des Flags --scopes Zugriffsbereiche an und beziehen Sie den Zugriffsbereich der Cloud Trace API trace.append ein. 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 Anmeldedaten zur Authentifizierung 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 für die Suche nach den Anmeldedaten Ihrer Anwendung.

Dafür gibt es drei Möglichkeiten:

  • Führen Sie gcloud auth application-default login aus

  • Legen Sie das Dienstkonto in einem Standardpfad für Ihr Betriebssystem ab. Nachfolgend sind die Standardpfade für Windows und Linux aufgeführt:

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

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

  • Legen Sie die Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS auf den Pfad zu Ihrem Dienstkonto fest:

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 in der Console sehen.

Trace-Anzeige öffnen

Problembehebung

Informationen zur Fehlerbehebung bei Cloud Trace finden Sie auf der Seite Fehlerbehebung.

Ressourcen