Abschnitt 16 · Lektion 5
Protokollieren
„Warum hat die Bestellung 4711 keine Bestätigung bekommen?“ „Seit wann sind die Antworten langsam?“ „Was ist um 3:14 Uhr passiert?“ Solche Fragen kommen am Tag danach. Beantworten lassen sie sich nur mit dem, was das Programm in dem Moment selbst ins Protokoll geschrieben hat, und zwar so, dass man es wiederfindet.
Sätze sind für Menschen, Zeilen sind für Werkzeuge
const ereignisse = [
{ anfrageId: "a1b2c3", pfad: "/api/buecher", status: 201, dauerMs: 1830 },
{ anfrageId: "d4e5f6", pfad: "/api/buecher/7", status: 200, dauerMs: 12 },
{ anfrageId: "g7h8i9", pfad: "/api/kaufen", status: 500, dauerMs: 2400 },
];
console.log("So, wenn du es selbst liest:");
for (const e of ereignisse) {
console.log(` Anfrage an ${e.pfad} war nach ${e.dauerMs} ms mit ${e.status} fertig`);
}
console.log("\nSo, wenn es jemand auswerten soll:");
const zeilen = ereignisse.map((e) =>
JSON.stringify({ zeit: "2026-08-14T09:12:00.000Z", level: e.status >= 500 ? "error" : "info", ...e })
);
for (const zeile of zeilen) console.log(` ${zeile}`);
// Die Frage von gestern: welche Anfragen brauchten laenger als eine Sekunde?
const langsam = zeilen.map((z) => JSON.parse(z)).filter((z) => z.dauerMs > 1000);
console.log(`\nLangsamer als 1000 ms: ${langsam.map((z) => z.anfrageId).join(", ")}`); Die erste Form liest sich besser. Sie ist trotzdem die schlechtere, sobald mehr als ein Mensch das Protokoll liest oder mehr als drei Zeilen darin stehen.
Der Grund steht am Ende des Beispiels. Die Frage „welche Anfragen brauchten länger als eine Sekunde“ ist auf der strukturierten Form eine Zeile Code. Auf der Satzform ist sie ein regulärer Ausdruck, der kaputtgeht, sobald jemand den Satz umformuliert.
Jeder Eintrag ist eine Zeile JSON ohne Einrückung. Die Werkzeuge, die Protokolle einsammeln, arbeiten nämlich zeilenweise. Ein über fünf Zeilen eingerücktes JSON würde dabei zu fünf zusammenhanglosen Einträgen.
Was in jeden Eintrag gehört
- Ein Zeitstempel, als Text im ISO-Format in UTC. In Ortszeit passen zwei Server nicht zusammen, und einmal im Jahr gibt es eine Stunde doppelt.
- Die Stufe, also
debug,info,warnodererror. - Die Meldung, kurz und stabil, am besten ein Ereignisname wie
bestellung_angelegtstatt eines Satzes, der sich morgen ändert. - Die Anfragekennung, damit zusammengehörende Zeilen zusammenfinden. Die hast du in Lektion 10.2
gebaut und in die Kopfzeile
X-Anfrage-Idgelegt. Hier wird sie zum Faden, an dem du zwanzig Zeilen einer Anfrage aus zehntausend anderen herausziehst.
Alles Weitere sind Felder, und Felder sind billig. Pfad, Methode, Statuscode, Dauer, die Kennung des betroffenen Eintrags.
Stufen zum Filtern
// Von leise nach laut. Die Reihenfolge ist der ganze Filter.
const STUFEN = ["debug", "info", "warn", "error"];
function laut(stufe) {
return STUFEN.indexOf(stufe) >= STUFEN.indexOf(process.env.LOG_LEVEL ?? "info");
}
for (const grenze of ["debug", "info", "error"]) {
process.env.LOG_LEVEL = grenze;
const durch = STUFEN.filter((stufe) => laut(stufe));
console.log(`LOG_LEVEL=${grenze.padEnd(6)} lässt durch: ${durch.join(", ")}`);
} Der ganze Filter ist eine Reihenfolge und ein Vergleich.
Mit den Stufen lässt du in der Produktion weg, was nur beim Entwickeln hilft. debug darf großzügig
sein und alles enthalten, weil es normalerweise nicht mitläuft. error ist teuer, weil es jemand
liest.
Die Grenze kommt aus der Umgebung, aus LOG_LEVEL. Willst du nachts um drei mehr sehen, änderst du
eine Variable und startest neu. Den Code ändern und neu ausliefern musst du dafür nicht.
Ich lege debug, info und warn auf stdout und nur error auf stderr, wie bei der Trennung aus
dem Abschnitt über Prozess und Umgebung. Auf welchem Kanal eine Zeile landet, hängt an der Funktion,
mit der geschrieben wird. console.log geht auf stdout und console.error auf stderr.
console.warn landet in Node ebenfalls auf stderr, auch wenn der Name nach einer eigenen Stufe
klingt.
Was nie hineingehört
Ein Passwort im Protokoll braucht keinen Angreifer. Es steht einfach da, in einer Datei, auf die oft mehr Leute Zugriff haben als auf die Datenbank, und die oft länger aufbewahrt wird als alles andere.
const GEHEIM = new Set(["passwort", "token", "authorization", "cookie"]);
function schwaerze(felder) {
return Object.fromEntries(
Object.entries(felder).map(([name, wert]) => [name, GEHEIM.has(name) ? "[entfernt]" : wert])
);
}
// So sieht eine Anmeldung aus, wenn man den ganzen Rumpf protokolliert.
const rumpf = { email: "test@example.com", passwort: "einlangesgeheimnis", merken: true };
console.log(`ungefiltert: ${JSON.stringify(rumpf)}`);
console.log(`geschwärzt: ${JSON.stringify(schwaerze(rumpf))}`);
// Und so, wenn das Passwort eine Ebene tiefer liegt.
const verschachtelt = { nutzer: { email: "test@example.com", passwort: "einlangesgeheimnis" } };
console.log(`verschachtelt: ${JSON.stringify(schwaerze(verschachtelt))}`); Dahin kommt es leicht. Jemand protokolliert den ganzen Rumpf einer Anfrage, um zu sehen, was
ankommt. Bei einer Anmeldung steht das Passwort mit drin, bei den Kopfzeilen das Sitzungscookie und
Authorization. Mit den beiden kann sich jemand anderes als dieser Nutzer ausgeben, solange sie
gelten.
Dagegen hilft Schwärzen. Der Wert eines solchen Felds wird durch einen Platzhalter ersetzt, und zwar im Logger selbst, denn an jeder Aufrufstelle einzeln wird irgendwann eine vergessen.
Einen Haken hat das, und den siehst du im verschachtelten Fall. Geschwärzt wird nur auf der obersten Ebene. Liegt das Passwort in einem verschachtelten Objekt, geht es durch. In echt läuft die Ersetzung deshalb rekursiv, oder protokolliert werden von vornherein nur ausgewählte Felder statt ganzer Objekte. Die zweite Lösung ist die bessere, weil eine Allowlist auch dann noch stimmt, wenn morgen jemand ein neues Feld hinzufügt.
Wohin geschrieben wird
Geschrieben wird auf stdout und stderr und sonst nirgendwohin.
Ein Programm, das selbst in eine Datei schreibt, muss sich um Dinge kümmern, die es nichts angehen. Wohin genau, wer das Verzeichnis lesen darf, was bei einem Neustart passiert, wie die Datei rotiert wird, bevor die Platte voll ist, und was zwei gleichzeitig laufende Instanzen mit derselben Datei machen.
Die Umgebung kann das besser. Sie sammelt stdout und stderr ein und bringt sie dorthin, wo Protokolle liegen, ob das Programm auf einem Server läuft, in einem Container oder als Funktion.
In der Aufgabe baust du in logger.js einen Logger mit Filter, Schwärzen und einer Zeile JSON je
Eintrag.
Zum Mitnehmen
Ein Protokolleintrag ist eine Zeile JSON mit Zeit in UTC, Stufe, Meldung und Anfragekennung, auf stdout oder bei error auf stderr. Passwörter, Token und Cookies schwärzt der Logger, bevor sie hineinkommen.
Jetzt du
Basis Konto, kostenlosZu dieser Lektion gehört eine Aufgabe. Du schreibst den Code selbst, und nach jedem Lauf sagt dir eine Prüfliste, was schon stimmt.
Dafür brauchst du das Basis Konto. Es kostet nichts, und ein Passwort gibt es auch nicht.
In diesem Kurs läuft dein Code auf einem Server. Dafür hat das Basis Konto 1 Stunde im Monat, mehr Zeit gibt es mit dem Premium Konto.
Was in dieser Lektion steckt
-
Artikel mit 3 Beispielen zum Ausprobieren
Steht hier, ohne Konto lesbar.
-
Aufgabe, dein Code läuft auf einem Server
Öffnet sich mit dem Basis Konto.