Anfragen-IDs in Node.js asynchronen Ketten mit AsyncLocalStorage sicher weitergeben

Einleitung

In modernen Microservices-Architekturen und komplexen Node.js-Anwendungen löst eine einzelne Benutzeranfrage oft eine Kaskade von asynchronen Operationen aus, die sich über mehrere Funktionen, Module und sogar externe Dienste erstrecken. Während sich diese Operationen entfalten, wird die Aufrechterhaltung des Kontexts – insbesondere einer eindeutigen Kennung für die ursprüngliche Anfrage – für effektives Logging, Debugging und Tracing unerlässlich. Ohne eine konsistente Methode zur Verfolgung der Reise einer Anfrage kann das Zusammenfügen einer Sequenz von Ereignissen aus unterschiedlichen Protokollen eine gewaltige Herausforderung darstellen, die zu verlängerten Debugging-Zeiten und einer reduzierten Systembeobachtbarkeit führt. Traditionelle Ansätze, die eine explizite Parameterübergabe beinhalten, werden schnell umständlich und fehleranfällig, überfrachten Funktionssignaturen und verletzen die Trennung von Belangen. Hier kommt Node.js' AsyncLocalStorage ins Spiel und bietet eine leistungsstarke und elegante Lösung zur sicheren Weitergabe anfragespezifischer Daten über die gesamte asynchrone Aufrufkette hinweg.

Asynchronen Kontext und AsyncLocalStorage verstehen

Bevor wir uns mit den praktischen Details befassen, wollen wir ein gemeinsames Verständnis der Schlüsselkonzepte festlegen.

Asynchroner Kontext

In Node.js ist der Ausführungsfluss von Natur aus asynchron. Operationen wie Netzwerkanfragen, Dateiein-/ausgabe oder Datenbankabfragen blockieren den Hauptthread nicht; stattdessen planen sie Rückrufe für eine spätere Ausführung. Diese nicht-blockierende Natur macht Node.js effizient, schafft aber auch Herausforderungen für die Kontextverwaltung. Wenn eine Funktion eine asynchrone Operation initiiert, kann der nachfolgende Code, der nach dem await oder in einem Rückruf ausgeführt wird, auf einem anderen "Tick" der Ereignisschleife ausgeführt werden, wodurch der Kontext des ursprünglichen Aufrufs verloren gehen kann.

Anfrage-ID

Eine Anfrage-ID ist eine eindeutige Kennung, die jeder eingehenden Anfrage (z. B. einer HTTP-Anfrage) zugewiesen wird. Diese ID dient als Korrelationsschlüssel und verknüpft alle Protokolle und Operationen, die als Teil der Verarbeitung dieser spezifischen Anfrage durchgeführt werden. Sie ist ein unverzichtbares Werkzeug für verteiltes Tracing und die Ursachenanalyse.

AsyncLocalStorage

AsyncLocalStorage ist eine Kern-API von Node.js, die zur Verwaltung des Kontexts über asynchrone Operationen hinweg eingeführt wurde. Stellen Sie es sich als Thread-lokalen Speicher vor, aber für asynchrone Aufrufketten. Sie ermöglicht es Ihnen, Daten zu speichern, die für einen asynchronen Kontext lokal sind, und diese Daten werden automatisch über await-Aufrufe, setTimeout, Promises und andere asynchrone Grenzen hinweg weitergegeben. Das bedeutet, Sie können eine AsyncLocalStorage-Instanz initialisieren, einen Wert speichern, und jede nachfolgende asynchrone Operation innerhalb dieses Kontexts kann auf denselben Wert zugreifen, ohne ihn explizit weitergeben zu müssen.

Wie funktioniert AsyncLocalStorage

AsyncLocalStorage erzielt seine Magie durch die Nutzung der internen asynchronen Haken von Node.js. Wenn Sie asyncLocalStorage.run(store, callback, ...args) aufrufen, wird ein neuer asynchroner Kontext erstellt. Jede innerhalb des callback initiierte asynchrone Operation erbt diesen Kontext, was bedeutet, dass asyncLocalStorage.getStore() das von Ihnen bereitgestellte store-Objekt zurückgibt. Wenn diese asynchrone Operation abgeschlossen ist, wird der Kontext automatisch aufgerollt. Diese kontextuelle Weitergabe funktioniert, ohne dass Sie jede Funktionssignatur ändern oder explizit Kontextobjekte übergeben müssen.

Anfrage-ID-Weitergabe mit AsyncLocalStorage implementieren

Lassen Sie uns veranschaulichen, wie AsyncLocalStorage verwendet wird, um eine Anfrage-ID während des Lebenszyklus einer HTTP-Anfrage weiterzugeben.

Grundlegende Einrichtung

Zuerst müssen wir AsyncLocalStorage importieren:

const { AsyncLocalStorage } = require('async_hooks');

// Eine Instanz von AsyncLocalStorage erstellen
const asyncLocalStorage = new AsyncLocalStorage();

Der Middleware-Ansatz

Der gebräuchlichste und effektivste Weg, AsyncLocalStorage in HTTP-Anfragen zu integrieren, ist über Middleware (z. B. in einer Express.js-Anwendung). Die Middleware ist verantwortlich für:

1. Generierung oder Extraktion einer Anfrage-ID.
2. Ausführung der restlichen Anfragebehandlungslogik innerhalb des AsyncLocalStorage-Kontexts, wobei die Anfrage-ID gespeichert wird.

const express = require('express');
const { AsyncLocalStorage } = require('async_hooks');
const crypto = require('crypto'); // Zum Generieren eindeutiger IDs

const app = express();
const asyncLocalStorage = new AsyncLocalStorage();

// Middleware zur Zuweisung und Weitergabe der Anfrage-ID
app.use((req, res, next) => {
  // Generiere eine eindeutige Anfrage-ID für jede eingehende Anfrage
  const requestId = crypto.randomBytes(16).toString('hex');
  
  // Speichere die requestId im AsyncLocalStorage-Kontext
  asyncLocalStorage.run({ requestId: requestId }, () => {
    // An das Request-Objekt anhängen für einfachen Zugriff (optional, aber praktisch)
    req.requestId = requestId;
    console.log(`[${requestId}] Eingehende Anfrage: ${req.method} ${req.url}`);
    next(); // Fahre mit der nächsten Middleware oder dem Routen-Handler fort
  });
});

// Ein Beispieldienst, der eine asynchrone Operation simuliert
const someService = {
  doSomethingAsync: async () => {
    await new Promise(resolve => setTimeout(resolve, 100)); // Asynchrone Arbeit simulieren
    const store = asyncLocalStorage.getStore();
    console.log(`[${store?.requestId || 'N/A'}] Service tut asynchron etwas.
`);
    return 'Operation abgeschlossen!';
  },
  
  // Eine weitere asynchrone Operation, die doSomethingAsync aufrufen könnte
  doAnotherThing: async (data) => {
    const store = asyncLocalStorage.getStore();
    console.log(`[${store?.requestId || 'N/A'}] Service hat Daten erhalten: ${data}`);
    const result = await someService.doSomethingAsync();
    return `Anderes erledigt: ${result}`;
  }
};

// Routen-Handler, der den Kontextzugriff demonstriert
app.get('/data', async (req, res) => {
  // Hole die Store-Daten (die die requestId enthalten) aus AsyncLocalStorage
  const store = asyncLocalStorage.getStore();
  const currentRequestId = store?.requestId || 'UNKNOWN';

  console.log(`[${currentRequestId}] Handler hat Anfrage erhalten.`);

  try {
    const serviceResult = await someService.doAnotherThing('einige Eingabedaten');
    res.json({ message: `Daten erfolgreich abgerufen, Anfrage-ID: ${currentRequestId}`, serviceResult });
  } catch (error) {
    console.error(`[${currentRequestId}] Fehler bei der Verarbeitung der Anfrage:`, error);
    res.status(500).json({ error: 'Interner Serverfehler' });
  }
});

const PORT = 3000;
app.listen(PORT, () => {
  console.log(`Server läuft auf Port ${PORT}`);
});

Erklärung des Codes

1. asyncLocalStorage.run({ requestId: requestId }, () => { ... });: Dies ist der Kern der Lösung. Wir erstellen für jede eingehende Anfrage einen neuen AsyncLocalStorage-Kontext. Das Objekt { requestId: requestId } ist der "Store", der in diesem Kontext verfügbar sein wird. Alle nachfolgenden asynchronen Operationen, die innerhalb der Funktion () => { ... }` initiiert werden, haben Zugriff auf diesen Store.
2. req.requestId = requestId;: Während AsyncLocalStorage die ID sicher weitergibt, bietet die Platzierung auf dem req-Objekt unmittelbaren, synchronen Zugriff innerhalb des aktuellen Middleware-Stacks, was für einfache Protokollierung praktisch sein kann, bevor AsyncLocalStorage.getStore() für die asynchrone Weitergabe bevorzugt wird.
3. asyncLocalStorage.getStore(): Innerhalb von someService.doSomethingAsync und app.get('/data') rufen wir asyncLocalStorage.getStore() auf. Diese Methode ruft das Store-Objekt ({ requestId: ... }) ab, das von asyncLocalStorage.run für den aktuellen asynchronen Kontext gesetzt wurde. Auch wenn doSomethingAsync nach einem await aufgerufen wird und potenziell Kontextwechsel beinhaltet, stellt AsyncLocalStorage sicher, dass die richtige requestId abgerufen wird.
4. Protokollierung: Beachten Sie, wie die requestId in den console.log-Anweisungen in der gesamten Anwendung verwendet wird, was eine klare Korrelation in den Protokollen bietet.

Anwendungsfälle

• Anforderungsverfolgung: Zentral für verteilte Tracing-Systeme, die eine eindeutige ID zur Verknüpfung von Protokollen über Dienste hinweg bereitstellt.
• Kontextbezogene Protokollierung: Fügen Sie automatisch eine Anfrage-ID in alle Protokollmeldungen während der Verarbeitung einer Anfrage ein, was Protokolle für die Fehlersuche exponentiell nützlicher macht.
• Benutzerinformationen: Über Anfrage-IDs hinaus können Sie Benutzer-IDs, Authentifizierungstoken oder Mandanten-IDs speichern, um kontextabhängige Zugriffskontrollen zu ermöglichen oder Daten zu personalisieren.
• Leistungsüberwachung: Verfolgen Sie die Startzeit einer Anfrage in AsyncLocalStorage, um die Latenz über verschiedene Teile der Anwendung hinweg zu berechnen.

Fazit

AsyncLocalStorage ist ein Game-Changer für die Verwaltung des asynchronen Kontexts in Node.js, insbesondere für kritische Anliegen wie die Weitergabe von Anfrage-IDs. Indem es einen sicheren, leistungsstarken und nicht-intrusiven Mechanismus zur Übertragung von kontextbezogenen Daten über asynchrone Grenzen hinweg bietet, verbessert es die Beobachtbarkeit, die Debuggability und die Wartbarkeit komplexer Node.js-Anwendungen erheblich. Die Nutzung von AsyncLocalStorage befreit Entwickler von der mühsamen Aufgabe der expliziten Kontextübergabe und ermöglicht es ihnen, sich auf die Geschäftslogik zu konzentrieren, während sie reichhaltigere, korrelierte Einblicke in das Verhalten ihrer Anwendungen erhalten. Es ist die definitive Lösung zur sicheren Weitergabe von anfragespezifischem Kontext durch komplexe asynchrone Aufrufketten.