Node.js und OpenTelemetry

Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Diese Seite richtet sich an Anwendungsentwickler, die Cloud Trace-Daten für Node.js-Anwendungen mit OpenTelemetry erfassen möchten. OpenTelemetry bietet eine Reihe von Instrumentierungsbibliotheken zum Erfassen von Trace- und Messwertdaten. Diese Bibliotheken funktionieren mit mehreren Back-Ends. So erfassen Sie Traces mit OpenTelemetry und Node.js:

  • Installieren Sie die OpenTelemetry-Pakete.
  • Anwendung für den Export von Spans nach Cloud Trace konfigurieren
  • Konfigurieren Sie Ihre Plattform.

Releaseinformationen finden Sie hier:

Informationen zu OpenTelemetry-Referenzinhalten finden Sie hier:

Aktuelle Informationen zu OpenTelemetry für Node.js sowie zusätzliche Dokumentation und Beispiele finden Sie unter OpenTelemetry.

Hinweis

Prüfen Sie, ob die Cloud Trace API für Ihr Google Cloud-Projekt aktiviert ist:

  1. Klicken Sie auf die folgende Schaltfläche oder wählen Sie in der Google Cloud Console APIs & Dienste und dann Cloud Trace API aus:

    Zur Trace API

  2. Wenn auf der Seite Cloud Trace API eine Schaltfläche mit der Bezeichnung Aktivieren angezeigt wird, klicken Sie darauf. Wenn diese Schaltfläche nicht angezeigt wird, ist die Cloud Trace API für das ausgewählte Projekt aktiviert.

Client installieren, initialisieren und verwenden

OpenTelemetry bietet drei Möglichkeiten zur Instrumentierung Ihrer Anwendung:

  • Automatische Instrumentierung für Node.js-Anwendungen

    Bei diesem Ansatz konfigurieren Sie Ihre Anwendung so, dass das @opentelemetry/sdk-trace-node SDK enthalten ist. Sie müssen jedoch keine Codeänderungen an den von Ihnen verwendeten Bibliotheken vornehmen.

  • Manuelles Tracing

    Bei diesem Ansatz ändern Sie die Bibliotheken, die Sie zum Erfassen von Trace-Informationen verwenden.

  • Automatische Instrumentierung für Webanwendungen

    Bei diesem Ansatz konfigurieren Sie Ihre Anwendung so, dass das @opentelemetry/sdk-trace-web SDK enthalten ist. Das SDK erfasst nutzerseitige Leistungsdaten, einschließlich Latenz und verteilter Traces, die Ihnen die Informationen zur Diagnose von Front-End-Problemen und zur Überwachung des Anwendungsstatus insgesamt liefern.

In den folgenden Abschnitten wird der Anwendungsfall für jede Instrumentierung dargestellt.

Automatische Instrumentierung

Das Modul @opentelemetry/sdk-trace-node bietet eine automatische Instrumentierung für Node.js-Anwendungen.

Bei der automatischen Instrumentierung wird Folgendes in Ihrer Anwendung automatisch erkannt:

  • Frameworks wie Express
  • Gängige Protokolle wie HTTP, HTTPS und gRPC
  • Datenbanken wie MySQL, MongoDB, Redis und PostgreSQL
  • Andere Bibliotheken in Ihrer Anwendung

Die automatische Instrumentierung bietet einsatzbereites Tracing, sodass Sie keine Codeänderungen an einer der von Ihnen verwendeten Bibliotheken vornehmen müssen. Der Instrumentierungscode führt automatisch die folgenden Aktionen aus:

  • Extrahiert eine Trace-Kontext-ID aus eingehenden Anfragen, um ggf. verteiltes Tracing zu ermöglichen.
  • Garantiert, dass der aktuelle Trace-Kontext weitergegeben wird, während die Transaktion eine Anwendung durchläuft.
  • Fügt die Trace-Kontext-ID zu ausgehenden Anfragen hinzu, damit der verteilte Trace gegebenenfalls auch mit dem nächsten Hop fortgesetzt werden kann.
  • Erstellt und beendet Spans.

Das Modul verwendet Plug-ins, um Ihre Anwendung automatisch zu instrumentieren, damit Spans erzeugt und ein End-to-End-Tracing mit nur wenigen Codezeilen bereitgestellt werden können.

Manuelle Instrumentierung

Das manuelle Tracing-Modul @opentelemetry/sdk-trace-base bietet vollständige Kontrolle über die Instrumentierung und die Span-Erstellung. async_hooks wird nicht geladen. Standardmäßig werden kein kontinuierlicher lokale Speicher oder Instrumentierungs-Plug-ins verwendet. Das manuelle Tracing hat im Vergleich zum Modul für die automatische Instrumente weniger Leistungseinsparungen.

Automatische Instrumentierung für Webanwendungen

Das Modul @opentelemetry/sdk-trace-web bietet automatisierte Instrumentierung und Tracing für Webanwendungen. Er erfasst clientseitige Leistungsdaten, einschließlich Latenz und verteilter Traces, die Ihnen Informationen zum Diagnostizieren von Front-End-Problemen und zur Überwachung des Gesamtstatus der Anwendung bieten.

Beispiel

Die folgende Anleitung zeigt, wie das Modul zur automatischen Instrumentierung für Compute Engine und Google Kubernetes Engine verwendet wird.

Compute Engine

Installieren Sie die folgenden Pakete:

npm install --save @opentelemetry/api
npm install --save @opentelemetry/sdk-trace-node
npm install --save @opentelemetry/sdk-trace-base
npm install --save @google-cloud/opentelemetry-cloud-trace-exporter

Fügen Sie Ihrer Anwendung den folgenden Code hinzu, um den Exporter zu initialisieren und zu registrieren:

const opentelemetry = require("@opentelemetry/api");
const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");
const { SimpleSpanProcessor } = require("@opentelemetry/sdk-trace-base");
const {
  TraceExporter,
} = require("@google-cloud/opentelemetry-cloud-trace-exporter");
// Enable OpenTelemetry exporters to export traces to Google Cloud Trace.
// Exporters use Application Default Credentials (ADCs) to authenticate.
// See https://developers.google.com/identity/protocols/application-default-credentials
// for more details.
const provider = new NodeTracerProvider();

// Initialize the exporter. When your application is running on Google Cloud,
// you don't need to provide auth credentials or a project id.
const exporter = new TraceExporter();

// Configure the span processor to send spans to the exporter
provider.addSpanProcessor(new SimpleSpanProcessor(exporter));

GKE

Fügen Sie Folgendes zu Dockerfile hinzu:

RUN npm install --save @opentelemetry/api
RUN npm install --save @opentelemetry/sdk-trace-node
RUN npm install --save @opentelemetry/sdk-trace-base
RUN npm install --save @google-cloud/opentelemetry-cloud-trace-exporter

Fügen Sie Ihrer Anwendung den folgenden Code hinzu, um den Exporter zu initialisieren und zu registrieren:

const opentelemetry = require("@opentelemetry/api");
const { NodeTracerProvider } = require("@opentelemetry/sdk-trace-node");
const { SimpleSpanProcessor } = require("@opentelemetry/sdk-trace-base");
const {
  TraceExporter,
} = require("@google-cloud/opentelemetry-cloud-trace-exporter");
// Enable OpenTelemetry exporters to export traces to Google Cloud Trace.
// Exporters use Application Default Credentials (ADCs) to authenticate.
// See https://developers.google.com/identity/protocols/application-default-credentials
// for more details.
const provider = new NodeTracerProvider();

// Initialize the exporter. When your application is running on Google Cloud,
// you don't need to provide auth credentials or a project id.
const exporter = new TraceExporter();

// Configure the span processor to send spans to the exporter
provider.addSpanProcessor(new SimpleSpanProcessor(exporter));

Beispielanwendung mit dem Express-Framework

Mit der OpenTelemetry-Express-Instrumentierung können Sie Trace-Daten automatisch erfassen und in das Back-End Ihrer Wahl für eine Beobachtbarkeit auf verteilte Systeme exportieren.

Führen Sie die folgenden Schritte aus, um OpenTelemetry für Anwendungen zu verwenden, die das Express-Framework ausführen:

  1. Installieren Sie die folgenden Pakete:

    npm install --save @opentelemetry/instrumentation-http
npm install --save @opentelemetry/instrumentation-express

  2. Fügen Sie Ihrer Anwendung den folgenden Code hinzu, der alle unterstützten Plug-ins lädt:

    const { NodeTracerProvider } = require('@opentelemetry/sdk-trace-node');
const provider = new NodeTracerProvider();

Ein einfaches Beispiel finden Sie im OpenTelemetry-Express-Beispiel.

Benutzerdefinierten Span erstellen

Sie können dem vom System erstellten Trace zusätzliche Informationen hinzufügen, indem Sie einen benutzerdefinierten Span erstellen.

Zum Erstellen eines benutzerdefinierten Spans fügen Sie dem Quellcode Folgendes hinzu:


// Initialize the OpenTelemetry APIs to use the
// NodeTracerProvider bindings
opentelemetry.trace.setGlobalTracerProvider(provider);
const tracer = opentelemetry.trace.getTracer("basic");

// Create a span.
const span = tracer.startSpan("foo");

// Set attributes to the span.
span.setAttribute("key", "value");

// Annotate our span to capture metadata about our operation
span.addEvent("invoking work");

// simulate some random work.
for (let i = 0; i <= Math.floor(Math.random() * 40000000); i += 1) {}

// Be sure to end the span.
span.end();

  • getTracer gibt eine Instanz von Tracer zurück, wobei basic der Name des Tracers oder der Instrumentierungsbibliothek ist. Dadurch wird OpenTelemetry mitgeteilt, wer Spans erstellt.

  • foo ist der Name des benutzerdefinierten Spans.

  • invoking work ist der Name des Beispielereignisses. Hier erfahren Sie, wie Sie die addEvent API verwenden.

Ein einfaches Beispiel zum Erstellen eines benutzerdefinierten Spans finden Sie im OpenTelemetry-Beispiel.

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.

Sie haben drei Möglichkeiten, diese Anmeldedaten anzugeben:

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

  • Legen Sie das Dienstkonto in einem Standardpfad für Ihr Betriebssystem ab. Im Folgenden 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"

Traces ansehen

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

Trace-Anzeige öffnen

Fehlerbehebung

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