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 Cloud Trace-Bibliothek für Node.js anpassen. In der Konfiguration der Bibliothek auf GitHub finden Sie eine Liste der Konfigurationsoptionen, die Sie mithilfe eines options-Objekts 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 sie in Google Cloud ausführen:

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

Wenn Sie eine Google Cloud-Infrastruktur ausführen, 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 der Infrastruktur ermittelt die cloud-trace-nodejs-Bibliothek für Node.js automatisch, ob die Umgebungsvariable GCLOUD_PROJECT festgelegt ist. enthält, verwendet die Bibliothek den Wert von GCLOUD_PROJECT als Google Cloud-Projekt-ID. Weitere Informationen zur Erkennungsdatei 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, müssen Sie dafür sorgen, dass der Zugriffsbereiche der Cloud Trace API aktiviert ist:

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

  • Geben Sie für gcloud-Nutzer Zugriffsbereiche mit dem Flag --scopes an und fügen Sie den Zugriffsbereich trace.append der Cloud Trace API 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 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. 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 Fehlerbehebung bei Cloud Trace finden Sie auf der Seite Fehlerbehebung.

Ressourcen