Traces und Messwerte mit Node.js generieren

In diesem Dokument wird beschrieben, wie Sie eine JavaScript-Anwendung in Node.js ändern, um Trace- und Messwertdaten mit dem Open-Source-Framework OpenTelemetry zu erfassen und strukturierte JSON-Logs in das Standard-Out-Format zu schreiben. Dieses Dokument enthält auch Informationen zu einer Node.js-Beispielanwendung, die Sie installieren und ausführen können. Die Anwendung verwendet das Web-Framework Fastify und ist so konfiguriert, dass Messwerte, Traces und Logs generiert werden.

Weitere Informationen zu Instrumentierung finden Sie in den folgenden Dokumenten:

• Instrumentierung und Beobachtbarkeit.
• Ansatz für die Instrumentierung auswählen

Manuelle und automatische Instrumentierung

Für diese Sprache definiert OpenTelemetry automatische Instrumentierung als die Erfassung von Telemetriedaten aus Bibliotheken und Frameworks, ohne Codeänderungen vorzunehmen. Sie müssen jedoch Module installieren und Umgebungsvariablen festlegen.

In diesem Dokument wird die manuelle Instrumentierung nicht beschrieben. Weitere Informationen zu diesem Thema finden Sie unter Automatische Instrumentierung für Node.

Allgemeine Informationen finden Sie unter OpenTelemetry-Instrumentierung für Knoten.

Hinweise

Enable the Cloud Logging, Cloud Monitoring, and Cloud Trace APIs.

Enable the APIs

Anwendung für die Erfassung von Traces, Messwerten und Logs instrumentieren

Führen Sie die folgenden Schritte aus, um Ihre Anwendung so zu instrumentieren, dass Trace- und Messwertdaten erfasst und strukturiertes JSON in die Standardausgabe geschrieben wird, wie in den folgenden Abschnitten dieses Dokuments beschrieben:

1. OpenTelemetry konfigurieren
2. Anwendung so konfigurieren, dass die OpenTelemetry-Konfiguration vorab geladen wird
3. Strukturiertes Logging konfigurieren
4. Strukturierte Logs schreiben

OpenTelemetry konfigurieren

Die Standardkonfiguration für das OpenTelemetry Node.js SDK exportiert Traces mithilfe des OTLP-Protokolls. Außerdem wird OpenTelemetry so konfiguriert, dass das Format W3C Trace Context zur Weitergabe von Trace-Kontext verwendet wird. Diese Konfiguration gewährleistet, dass Spans die richtige hierarchische Beziehung in einem Trace haben.

Das folgende Codebeispiel zeigt ein JavaScript-Modul zum Einrichten von OpenTelemetry.

Wenn Sie sich das vollständige Beispiel ansehen möchten, klicken Sie auf  Mehr und wählen Sie dann Auf GitHub ansehen aus.

diag.setLogger(
  new DiagConsoleLogger(),
  opentelemetry.core.getEnv().OTEL_LOG_LEVEL
);

const sdk = new opentelemetry.NodeSDK({
  instrumentations: getNodeAutoInstrumentations({
    // Disable noisy instrumentations
    '@opentelemetry/instrumentation-fs': {enabled: false},
  }),
  resourceDetectors: getResourceDetectorsFromEnv(),
  metricReader: getMetricReader(),
});

try {
  sdk.start();
  diag.info('OpenTelemetry automatic instrumentation started successfully');
} catch (error) {
  diag.error(
    'Error initializing OpenTelemetry SDK. Your application is not instrumented and will not produce telemetry',
    error
  );
}

// Gracefully shut down the SDK to flush telemetry when the program exits
process.on('SIGTERM', () => {
  sdk
    .shutdown()
    .then(() => diag.debug('OpenTelemetry SDK terminated'))
    .catch(error => diag.error('Error terminating OpenTelemetry SDK', error));
});

Im vorherigen Codebeispiel wird OpenTelemetry so konfiguriert, dass Messwerte mithilfe des OTLP-Protokolls exportiert werden. Außerdem wird das Paket @opentelemetry/auto-instrumentations-node verwendet, um alle verfügbaren Node.js-Instrumentierungen zu konfigurieren.

Damit alle ausstehenden Telemetriedaten geleert und Verbindungen vor dem Herunterfahren der Anwendung ordnungsgemäß geschlossen werden, ruft der SIGTERM-Handler shutdown auf.

Weitere Informationen und Konfigurationsoptionen finden Sie unter Automatische OpenTelemetry-Node.js-Instrumentierung.

Anwendung so konfigurieren, dass die OpenTelemetry-Konfiguration vorab geladen wird

Wenn Sie die Anwendung so konfigurieren möchten, dass strukturierte Logs geschrieben und Messwerte und Trace-Daten mit OpenTelemetry erfasst werden, aktualisieren Sie den Aufruf Ihrer Anwendung so, dass das Instrumentierungsmodul mit Node.js --require-Flag vorab geladen wird. Mit dem Flag --require wird sichergestellt, dass OpenTelemetry initialisiert wird, bevor Ihre Anwendung gestartet wird. Weitere Informationen finden Sie unter Erste Schritte mit OpenTelemetry Node.js.

Das folgende Codebeispiel zeigt ein Dockerfile, das das Flag --require übergibt:

CMD node --require ./build/src/instrumentation.js build/src/index.js 2>&1 | tee /var/log/app.log

Strukturiertes Logging konfigurieren

Wenn Sie die Trace-Informationen in die JSON-formatierten Logs aufnehmen möchten, die in die Standardausgabe geschrieben werden, konfigurieren Sie Ihre Anwendung so, dass strukturierte Logs im JSON-Format ausgegeben werden. Fastify verwendet das Pino-Log-Framework und stellt in jedem Anfrage-Handler einen Logger bereit. Das folgende Codebeispiel zeigt ein Pino-LoggerOptions-Objekt, das die Anwendung für die Ausgabe strukturierter JSON-Logs konfiguriert:

// Expected attributes that OpenTelemetry adds to correlate logs with spans
interface LogRecord {
  trace_id?: string;
  span_id?: string;
  trace_flags?: string;
  [key: string]: unknown;
}

// https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry#logseverity
const PinoLevelToSeverityLookup: Record<string, string | undefined> = {
  trace: 'DEBUG',
  debug: 'DEBUG',
  info: 'INFO',
  warn: 'WARNING',
  error: 'ERROR',
  fatal: 'CRITICAL',
};

export const loggerConfig = {
  messageKey: 'message',
  // Same as pino.stdTimeFunctions.isoTime but uses "timestamp" key instead of "time"
  timestamp(): string {
    return `,"timestamp":"${new Date(Date.now()).toISOString()}"`;
  },
  formatters: {
    log(object: LogRecord): Record<string, unknown> {
      // Add trace context attributes following Cloud Logging structured log format described
      // in https://cloud.google.com/logging/docs/structured-logging#special-payload-fields
      const {trace_id, span_id, trace_flags, ...rest} = object;

      return {
        'logging.googleapis.com/trace': trace_id,
        'logging.googleapis.com/spanId': span_id,
        'logging.googleapis.com/trace_sampled': trace_flags
          ? trace_flags === '01'
          : undefined,
        ...rest,
      };
    },
    // See
    // https://getpino.io/#/docs/help?id=mapping-pino-log-levels-to-google-cloud-logging-stackdriver-severity-levels
    level(label: string) {
      return {
        severity:
          PinoLevelToSeverityLookup[label] ?? PinoLevelToSeverityLookup['info'],
      };
    },
  },
} satisfies LoggerOptions;

Die vorherige Konfiguration extrahiert Informationen zum aktiven Span aus der Lognachricht und fügt diese Informationen dann als Attribute dem strukturierten JSON-Log hinzu. Mit diesen Attributen können Sie dann ein Log mit einem Trace korrelieren:

• logging.googleapis.com/trace: Der Ressourcenname des Trace, das mit dem Logeintrag verknüpft ist.
• logging.googleapis.com/spanId: Die Span-ID mit dem Trace, das dem Logeintrag zugeordnet ist.
• logging.googleapis.com/trace_sampled: Der Wert dieses Felds muss true oder false sein.

Weitere Informationen zu diesen Feldern finden Sie in der LogEntry-Struktur.

Wenn Sie die Pino-Konfiguration mit Fastify verwenden möchten, übergeben Sie beim Erstellen der Fastify-Anwendung das Logger-Konfigurationsobjekt:

// Create the Fastify app providing the Pino logger config
const fastify = Fastify({
  logger: loggerConfig,
});

Strukturierte Logs schreiben

Verwenden Sie den von Fastify bereitgestellten Pino-Logger, um strukturierte Logs zu schreiben, die mit einem Trace verknüpft sind. Die folgende Anweisung zeigt beispielsweise, wie die Methode Logger.info() aufgerufen wird:

request.log.info({subRequests}, 'handle /multi request');

OpenTelemetry füllt die Pino-Logeinträge automatisch mit dem Span-Kontext des aktuellen aktiven Spans im OpenTelemetry-Kontext. Dieser Span-Kontext wird dann in die JSON-Logs eingefügt, wie unter Strukturiertes Logging konfigurieren beschrieben.

Beispielanwendung ausführen, die für die Erfassung von Telemetriedaten konfiguriert ist

Die Beispielanwendung verwendet anbieterneutrale Formate, einschließlich JSON für Logs und OTLP für Messwerte und Traces sowie das Fastify-Framework. In diesem Beispiel wird die OpenTelemetry-Collector verwendet, die mit Google-Exportern konfiguriert wurde, um die Telemetrie an Google Cloud weiterzuleiten. Die Anwendung hat zwei Endpunkte:

• Der /multi-Endpunkt wird von der handleMulti-Funktion verarbeitet. Der Lastgenerator in der Anwendung gibt Anfragen an den Endpunkt /multi aus. Wenn dieser Endpunkt eine Anfrage empfängt, sendet er zwischen drei und sieben Anfragen an den Endpunkt /single auf dem lokalen Server.

  /**
   * handleMulti handles an http request by making 3-7 http requests to the /single endpoint.
   *
   * OpenTelemetry instrumentation requires no changes here. It will automatically generate a
   * span for the handler body.
   */
  fastify.get('/multi', async request => {
    const subRequests = randInt(3, 8);
    request.log.info({subRequests}, 'handle /multi request');
  
    for (let i = 0; i < subRequests; i++) {
      await axios.get(`http://localhost:${port}/single`);
    }
    return 'ok';
  });

• Der /single-Endpunkt wird von der handleSingle-Funktion verarbeitet. Wenn dieser Endpunkt eine Anfrage empfängt, wechselt er für eine kurze Verzögerung in den Ruhemodus und antwortet dann mit einem String.

  /**
   * handleSingle handles an http request by sleeping for 100-200 ms. It writes the number of
   * milliseconds slept as its response.
   */
  fastify.get('/single', async request => {
    // Sleep between 100-200 milliseconds
    const sleepMillis = randInt(100, 200);
    request.log.info({sleepMillis}, 'Going to sleep');
    await sleep(sleepMillis);
    return `slept ${sleepMillis}\n`;
  });

Anwendung herunterladen und bereitstellen

Hinweis: Wir empfehlen, die Beispielanwendung mit Cloud Shell auszuführen. Wenn Sie die Beispielanwendung jedoch lokal unter Linux oder Mac ausführen möchten, überspringen Sie den ersten Schritt der folgenden Anleitung.

So führen Sie das Beispiel aus:

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. Klonen Sie das Repository:

   git clone https://github.com/GoogleCloudPlatform/opentelemetry-operations-js
   

3. Gehen Sie zum Beispielverzeichnis:

   cd opentelemetry-operations-js/samples/instrumentation-quickstart
   

4. Erstellen Sie das Beispiel und führen Sie es aus:

   docker compose up --abort-on-container-exit
   

   Wenn Sie Cloud Shell nicht ausführen, führen Sie die Anwendung mit der Umgebungsvariable GOOGLE_APPLICATION_CREDENTIALS aus, die auf eine Datei mit Anmeldedaten verweist. Standardanmeldedaten für Anwendungen stellt eine Datei mit Anmeldedaten unter $HOME/.config/gcloud/application_default_credentials.json bereit.

   # Set environment variables
   export GOOGLE_CLOUD_PROJECT="PROJECT_ID"
   export GOOGLE_APPLICATION_CREDENTIALS="$HOME/.config/gcloud/application_default_credentials.json"
   export USERID="$(id -u)"
   
   # Run
   docker compose -f docker-compose.yaml -f docker-compose.creds.yaml up --abort-on-container-exit
   

Messwerte ansehen

Die OpenTelemetry-Instrumentierung in der Beispielanwendung generiert Prometheus-Messwerte, die Sie mit dem Metrics Explorer aufrufen können:

• Prometheus/http_server_duration_milliseconds/histogram zeichnet die Dauer von Serveranfragen auf und speichert die Ergebnisse in einem Histogramm.

• Prometheus/http_client_duration_milliseconds/histogram zeichnet die Dauer von Clientanfragen auf und speichert die Ergebnisse in einem Histogramm.

So rufen Sie die von der Beispielanwendung generierten Messwerte auf:

1. Rufen Sie in der Google Cloud Console die Seite Metrics Explorer auf.

   Zum Metrics Explorer

   Wenn Sie diese Seite über die Suchleiste suchen, wählen Sie das Ergebnis aus, dessen Zwischenüberschrift Monitoring ist.

2. Maximieren Sie im Element Messwert das Menü Messwert auswählen, geben Sie http_server in die Filterleiste ein und wählen Sie dann über die Untermenüs einen bestimmten Ressourcentyp und Messwert aus:
   1. Wählen Sie im Menü Aktive Ressourcen die Option Prometheus-Ziel aus.
   2. Wählen Sie im Menü Aktive Messwertkategorien die Option Http aus.
   3. Wählen Sie im Menü Aktive Messwerte einen Messwert aus.
   4. Klicken Sie auf Anwenden.
3. Konfigurieren Sie, wie die Daten angezeigt werden.
   

   Wenn die Messungen für einen Messwert kumulativ sind, normalisiert Metrics Explorer die gemessenen Daten automatisch nach dem Ausrichtungszeitraum. Dadurch wird im Diagramm eine Rate angezeigt. Weitere Informationen finden Sie unter Arten, Typen und Umwandlungen.

   Wenn ganzzahlige oder doppelte Werte gemessen werden, z. B. mit den beiden counter-Messwerten, summiert der Metrics Explorer automatisch alle Zeitachsen. Wenn Sie die Daten für die HTTP-Routen /multi und /single aufrufen möchten, legen Sie im ersten Menü des Eintrags Aggregation die Option Keine fest.

   Weitere Informationen zum Konfigurieren eines Diagramms finden Sie unter Messwerte bei Verwendung von Metrics Explorer auswählen.

Traces ansehen

So rufen Sie Ihre Trace-Daten auf:

1. Rufen Sie in der Google Cloud Console die Seite Trace Explorer auf:

   Zum Trace Explorer

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

2. Wählen Sie im Streudiagramm einen Trace mit dem URI /multi aus.

3. Wählen Sie im Gantt-Diagramm im Bereich Trace-Details den Span mit der Bezeichnung /multi aus.

   Ein Steuerfeld mit Informationen zur HTTP-Anfrage wird geöffnet. Zu diesen Details gehören die Methode, der Statuscode, die Anzahl der Byte und der User-Agent des Aufrufers.

4. Wählen Sie den Tab Logs und Ereignisse aus, um die mit diesem Trace verknüpften Logs aufzurufen.

   Auf dem Tab werden einzelne Logs angezeigt. Maximieren Sie den Logeintrag, um die Details anzusehen. Sie können auch auf Logs ansehen klicken und das Log mit dem Log-Explorer aufrufen.

Weitere Informationen zur Verwendung von Cloud Trace-Explorer finden Sie unter Traces suchen und untersuchen.

Logs ansehen

Im Log-Explorer können Sie Ihre Logs prüfen und sich auch die zugehörigen Traces ansehen, sofern vorhanden.

1. Rufen Sie in der Google Cloud Console die Seite Log-Explorer auf.

   Zum Log-Explorer

   Wenn Sie diese Seite über die Suchleiste suchen, wählen Sie das Ergebnis aus, dessen Zwischenüberschrift Logging ist.

2. Suchen Sie ein Log mit der Beschreibung handle /multi request.

   Erweitern Sie den Logeintrag, um die Details des Logs aufzurufen.

3. Klicken Sie auf Traces für einen Logeintrag mit der Nachricht "handle /multi request" und wählen Sie dann Trace-Details anzeigen aus.

   Der Bereich Trace-Details wird geöffnet und zeigt den ausgewählten Trace an.

Weitere Informationen zur Verwendung des Log-Explorers finden Sie unter Logs mit dem Log-Explorer ansehen.

Nächste Schritte

• OpenTelemetry
• OTLP-Spezifikation
• Strukturiertes Logging
• Fehlerbehebung für Managed Service for Prometheus
• Fehlerbehebung für Cloud Trace