Diese Seite wurde von der Cloud Translation API übersetzt.

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:

Node.js 14 oder höher
Die Releaserichtlinie für Node.js 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:

Compute Engine
Google Kubernetes Engine (GKE)
Flexible App Engine-Umgebung
App Engine-Standardumgebung
Außerhalb der GCP (Informationen zu den zusätzlichen Konfigurationsanforderungen finden Sie unter Profilerstellung für Code außerhalb der Google Cloud Platform.)

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

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

Führen Sie dazu diesen Befehl aus:

gcloud services enable cloudprofiler.googleapis.com

Weitere Informationen finden Sie unter gcloud services.

Google Cloud Console

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

Dienstkonto eine IAM-Rolle zuweisen

Wenn Sie Ihre Anwendung auf Google Cloud-Ressourcen bereitstellen, das Standarddienstkonto verwenden und die Rollenzuweisungen für dieses Dienstkonto nicht geändert haben, können Sie diesen Abschnitt überspringen.

In folgenden Fällen müssen Sie dem Dienstkonto die IAM-Rolle Cloud Profiler-Agent (roles/cloudprofiler.agent) zuweisen:

Sie verwenden das Standarddienstkonto, haben aber seine Rollenzuweisungen geändert.
Sie verwenden ein vom Nutzer erstelltes Dienstkonto.
Sie verwenden Workload Identity und gewähren dem Kubernetes-Dienstkonto die Rolle „Cloud Profiler-Agent“.

Sie können einem Dienstkonto eine IAM-Rolle mithilfe der Google Cloud Console oder der Google Cloud CLI zuweisen. Sie können beispielsweise den Befehl gcloud projects add-iam-policy-binding verwenden:

gcloud projects add-iam-policy-binding GCP_PROJECT_ID \
    --member serviceAccount:MY_SVC_ACCT_ID@GCP_PROJECT_ID.iam.gserviceaccount.com \
    --role roles/cloudprofiler.agent

Ersetzen Sie vor dem Ausführen des Befehls Folgendes:

GCP_PROJECT_ID: Ihre Projekt-ID.
MY_SVC_ACCT_ID: Name Ihres Dienstkontos.

Weitere Informationen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

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 integrierten Modul ab. Vorgefertigte Binärdateien für dieses integrierte Modul sind für Linux und Alpine Linux für Node 14 und 16 verfügbar. Es sind keine zusätzlichen Abhängigkeiten erforderlich. @google-cloud/profiler verwendet node-pre-gyp, um zu ermitteln, welche vorgefertigte Binärdatei installiert werden soll.

Wenn Sie @google-cloud/profiler in anderen Umgebungen verwenden, in denen keine vorkompilierten Binärdateien vorhanden sind, wird das Modul node-gyp zum Erstellen von Binärdateien verwendet. Informationen zu den Abhängigkeiten, die zum Erstellen von Binärdateien mit node-gyp erforderlich sind, finden Sie in der Installationsdokumentation von node-gyp.

Installation

So installieren Sie die neueste Version von Cloud Profiler:

    npm install --save @google-cloud/profiler

Wenn Sie auch den Trace-Agent verwenden möchten, müssen Sie beim Ändern der Anwendung das Profiler-Paket nach dem Trace-Agent-Paket (@google-cloud/trace-agent) importieren.

Compute Engine

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

Installieren Sie die neueste Version von Cloud Profiler:
```
npm install --save @google-cloud/profiler
```
Ä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:

Ändern Sie das Dockerfile so, dass das Profiler-Paket installiert wird:
```
FROM node:10
...
RUN npm install @google-cloud/profiler
```
Ä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.

Rufen Sie in der Google Cloud Console die Seite Profiler auf:

Gehen Sie zum Profiler.

Sie können diese Seite auch über die Suchleiste finden.

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 Ihrem Dockerfile einige Buildabhängigkeiten:

ERR! stack Error: not found: make

Fügen Sie der Build-Phase Ihres 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.