Profilerstellung für Node.js-Code

Auf dieser Seite wird beschrieben, wie Sie Ihre Node.js-Anwendung so ändern, dass Datenprofile erstellt und an Ihr Google Cloud-Projekt gesendet werden können. Allgemeine Informationen zur Profilerstellung finden Sie unter Konzepte der Profilerstellung.

Profiltypen für Node.js:

  • Heap
  • Echtzeit

Unterstützte Node.js-Sprachversionen:

  • 10.4.1 oder höher im 10.x-Versionszweig
  • 12.0.0 oder höher im 12.x-Versionszweig
  • 14.0.0 oder höher im 14.x-Versionszweig.
  • Die Node.js-Releaserichtlinie finden Sie unter Releasezeitplan.

Unterstützte Profiler-Agent-Versionen:

  • Der neueste Release des Agents wird unterstützt. Im Allgemeinen werden Releases, die älter als ein Jahr sind, nicht unterstützt. Wir empfehlen, die neueste veröffentlichte Version des Agents zu verwenden.

Unterstützte Betriebssysteme:

  • Linux: Die Profilerstellung für Node.js-Anwendungen wird für Linux-Kernel unterstützt, deren Standard-C-Bibliothek mit glibc oder mit musl implementiert wurde. Konfigurationsinformationen zu Linux Alpine-Kernels finden Sie unter Mit Linux Alpine ausführen.

Unterstützte Umgebungen:

Profiler API aktivieren

Sorgen Sie vor Verwendung des Profiler-Agents dafür, dass die zugrunde liegende Profiler API aktiviert ist. Sie können den Status der API prüfen und sie bei Bedarf über die Google Cloud-Befehlszeile oder die Google Cloud Console aktivieren:

gcloud-CLI

  1. Wenn Sie die Google Cloud-Befehlszeile noch nicht auf Ihrer Workstation installiert haben, lesen Sie die Dokumentation zur Google Cloud-Befehlszeile.

  2. Führen Sie dazu diesen Befehl aus:

    gcloud services enable cloudprofiler.googleapis.com
    

Weitere Informationen finden Sie unter gcloud services.

Google Cloud Console

  1. Wählen Sie im Navigationsbereich der Google Cloud Console APIs und Dienste aus, klicken Sie auf APIs und Dienste aktivieren und aktivieren Sie dann die Cloud Profiler API:

    Zu den Einstellungen für die Profiler API

  2. Wenn API aktiviert angezeigt wird, ist die API bereits aktiviert. Falls nicht, klicken Sie auf die Schaltfläche Aktivieren.

Cloud Profiler verwenden

Sie verwenden Profiler, indem Sie das Paket @google-cloud/profiler installieren, Ihrer Anwendung eine require-Anweisung hinzufügen und die Anwendung dann wie gewohnt bereitstellen. Dies gilt für alle unterstützten Umgebungen.

Vor dem Installieren von @google-cloud/profiler

Das Paket @google-cloud/profiler hängt von einem nativen Modul ab. Vorgefertigte Binärdateien für dieses native Modul sind für alle unterstützten Kombinationen aus Sprache und Plattform verfügbar. Um zu ermitteln, welche vorgefertigte Binärdatei installiert werden soll, verwendet @google-cloud/profiler node-pre-gyp.

Installation

So installieren Sie die neueste Version von Cloud Profiler:

    npm install --save @google-cloud/profiler

Falls Sie auch den Trace-Agent verwenden, importieren Sie beim Ändern Ihrer Anwendung das Profiler-Paket nach dem Trace-Agent-Paket (@google-cloud/trace-agent).

Compute Engine

Führen Sie für Compute Engine folgende Schritte aus:

  1. Installieren Sie die neueste Version von Cloud Profiler:

    npm install --save @google-cloud/profiler
    
  2. Ändern Sie den require-Code Ihre Anwendung so, dass ein serviceContext-Objekt erstellt wird, in dem service der Name des Dienstes zugewiesen wird, für den ein Profil zu erstellen ist. Optional können Sie für version die Version des Dienstes angeben, für den Sie ein Profil erstellen. Weitere Informationen zu diesen Konfigurationsoptionen finden Sie unter Argumente für Dienstnamen und -versionen:

    require('@google-cloud/profiler').start({
      serviceContext: {
        service: 'your-service',
        version: '1.0.0',
      },
    });

GKE

Führen Sie für GKE die folgenden Schritte aus:

  1. Ändern Sie das Dockerfile so, dass das Profiler-Paket installiert wird:

    FROM node:10
    ...
    RUN npm install @google-cloud/profiler
    
  2. Ändern Sie den require-Code Ihre Anwendung so, dass ein serviceContext-Objekt erstellt wird, in dem service der Name des Dienstes zugewiesen wird, für den ein Profil zu erstellen ist. Optional können Sie für version die Version des Dienstes angeben, für den Sie ein Profil erstellen. Weitere Informationen zu diesen Konfigurationsoptionen finden Sie unter Argumente für Dienstnamen und -versionen:

    require('@google-cloud/profiler').start({
      serviceContext: {
        service: 'your-service',
        version: '1.0.0',
      },
    });

App Engine

In der flexiblen App Engine-Umgebung und in der App Engine-Standardumgebung sieht der require-Code in etwa so aus:

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

In App Engine werden die Parameter service und version aus der Umgebung abgeleitet, sodass Sie diese nicht angeben müssen. Daher müssen Sie kein serviceContext-Objekt erstellen.

Daten analysieren

Nachdem Profiler Daten erfasst hat, können Sie diese mit der Profiler-Oberfläche ansehen und analysieren.

Wählen Sie im Navigationsbereich der Google Cloud Console Profiler aus:

Zu Profiler

Argumente für Dienstnamen und -versionen

Wenn Sie den Profiler-Agent laden, geben Sie zu dessen Konfiguration ein Argument für den Dienstnamen und ein optionales Argument für die Dienstversion an.

Profiler kann Daten für alle Replikate des unter Dienstname angegebenen Dienstes erfassen. Der Profiler-Dienst hat eine durchschnittliche Erfassungsrate von einem Profil pro Minute für jede Kombination aus Dienstversion und Zone jedes Dienstnamens.

Beispielsweise erstellt Profiler für einen Dienst mit zwei Versionen, dessen Replikate in drei Zonen ausgeführt werden, durchschnittlich sechs Profile pro Minute.

Wenn Sie für die Replikate unterschiedliche Dienstnamen verwenden, werden Dienstprofile häufiger als nötig mit einem entsprechend höheren Overhead erstellt.

Berücksichtigen Sie beim Auswählen eines Dienstnamens Folgendes:

  • Wählen Sie einen Namen aus, der den Dienst in Ihrer Anwendungsarchitektur klar darstellt. Wenn Sie nur einen einzigen Dienst oder eine einzige Anwendung ausführen, spielt der Dienstname eine untergeordnete Rolle. Er gewinnt aber an Bedeutung, wenn Ihre Anwendung beispielsweise in Form mehrerer Mikrodienste ausgeführt wird.

  • Achten Sie darauf, keine prozessspezifischen Werte wie eine Prozess-ID im String für den Dienstnamen zu verwenden.

  • Der String für den Dienstnamen muss diesem regulären Ausdruck entsprechen:

    ^[a-z0-9]([-a-z0-9_.]{0,253}[a-z0-9])?$

Es empfiehlt sich, einen statischen String wie imageproc-service als Dienstnamen zu verwenden.

Die Dienstversion ist optional. Wenn Sie die Dienstversion angeben, kann Profiler Profilinformationen aus mehreren Instanzen aggregieren und korrekt anzeigen. Sie können so verschiedene Versionen Ihrer Dienste kennzeichnen, wenn diese bereitgestellt werden. Die Profiler-Oberfläche ermöglicht Ihnen, die Daten nach Dienstversion zu filtern. So können Sie die Leistung von älteren und neueren Versionen des Codes vergleichen.

Obwohl der Wert des Dienstversionsarguments ein Freitextstring ist, sehen die Werte für dieses Argument meist wie Versionsnummern aus, zum Beispiel 1.0.0 oder 2.1.2.

Agent-Logging

Der Profiler-Agent kann Logging-Informationen schreiben. Wenn Sie Logging aktivieren möchten, legen Sie beim Starten des Agents die Option logLevel fest. Folgende logLevel-Werte werden unterstützt:

  • 0: Deaktiviert das Agent-Logging.
  • 1: Aktiviert das Fehler-Logging.
  • 2: Aktiviert das Warnungs-Logging (Standard).
  • 3: Aktiviert das Informations-Logging.
  • 4: Aktiviert das Fehlerbehebungs-Logging.

Legen Sie den logLevel-Wert im selben Objekt fest, das den Dienstkontext bereitstellt:

require('@google-cloud/profiler').start({
    serviceContext: { ... }
    logLevel:       3
});

Mit Linux Alpine ausführen

Der Node.js-Profiler-Agent für Linux Alpine wird nur für Google Kubernetes Engine-Konfigurationen unterstützt.

Build-Fehler

Wenn Sie npm install ausführen und der Build mit dem folgenden Fehler fehlschlägt, fehlen im Dockerfile einige Build-Abhängigkeiten:

ERR! stack Error: not found: make

Fügen Sie der Build-Phase des Dockerfiles die folgende Anweisung hinzu, um dieses Problem zu beheben:

RUN apk add python3 g++ make

Authentifizierungsfehler

Wenn Sie Docker-Images wie golang:alpine oder nur alpine verwenden, die mit Linux Alpine ausgeführt werden, wird möglicherweise der folgende Authentifizierungsfehler angezeigt:

connection error: desc = "transport: authentication handshake failed: x509: failed to load system roots and no roots provided"

Der Fehler ist nur sichtbar, wenn Agent-Logging aktiviert ist.

Der Fehler zeigt an, dass die Root-SSL-Zertifikate für die Docker-Images mit Linux Alpine nicht standardmäßig installiert sind. Diese Zertifikate sind erforderlich, damit der Profiler-Agent mit der Profiler API kommunizieren kann. Fügen Sie Ihrem Dockerfile den folgenden apk-Befehl hinzu, um diesen Fehler zu beheben:

FROM alpine
...
RUN apk add --no-cache ca-certificates

Sie müssen dann Ihre Anwendung neu erstellen und noch einmal bereitstellen.

Bekannte Probleme

Der Profiler-Agent für Node.js stört das normale Beenden des Programms. Es kann bis zu einer Stunde dauern, bis das Programm beendet ist, nachdem alle Aufgaben im Programm abgeschlossen wurden. Wenn Sie ein SIGINT ausgeben, z. B. indem Sie Ctrl-C verwenden, wird der Prozess ordnungsgemäß beendet.

Nächste Schritte