mitmario.dev

Exit-Codes und stderr

Node.js Sandbox 4 Min Lesezeit 4 BeispieleLektion 3 von 7

Von Hand startet dein Programm kaum jemand. Meistens wird es von einem anderen Programm aufgerufen, von einem Skript, einem Build, einem Cronjob oder einer Pipeline, also einer Kette von Schritten, die ein Server bei jeder Änderung am Code abarbeitet (CI). Die lesen nicht, was du schreibst. Sie schauen auf eine Zahl.

Im Browser ist eine Ausgabe für Augen gedacht. Hier wandert sie oft weiter in ein anderes Programm. Und das braucht von deinem Werkzeug zwei Dinge, eine Zahl am Ende und eine saubere Trennung zwischen dem Ergebnis und den Meldungen.

Die Zahl am Ende

Jeder Prozess hinterlässt beim Beenden einen Exit-Code, eine Zahl zwischen 0 und 255.

0 heißt, es hat geklappt. Jede andere Zahl heißt, es hat nicht geklappt. Mehr steckt in der Verabredung nicht drin. Welche Zahl du für welchen Fehler nimmst, ist deine Sache, und die Werkzeuge in diesem Kurs kommen mit 1 aus.

Deshalb führt befehl-a && befehl-b den zweiten Befehl nur aus, wenn der erste eine 0 hinterlassen hat. Und eine CI-Pipeline wird rot, sobald irgendein Schritt etwas anderes als 0 zurückgibt.

Kommt dein Skript ohne Absturz bis zur letzten Zeile, ist der Code von selbst 0. Dafür musst du nichts tun. Interessant wird es erst, wenn du Misserfolg melden willst.

Zwei Wege, Misserfolg zu melden

Der erste ist process.exit(1). Der beendet den Prozess sofort, mitten in allem, was gerade läuft.

Was process.exit verschluckt
console.log("Start");

setTimeout(() => {
  console.log("Aufräumen erledigt");
}, 0);

process.exit(1);

Das setTimeout war angemeldet, aber es kommt nie dran. Die Zeile „Aufräumen erledigt“ wird nie geschrieben. Bei einem Aufräumschritt ist das ärgerlich. Bei einer laufenden Schreiboperation bleibt die Datei leer oder halb geschrieben liegen.

Der zweite Weg ist process.exitCode = 1.

Dieselbe Absicht, aber sanft
console.log("Start");

setTimeout(() => {
  console.log("Aufräumen erledigt");
}, 0);

process.exitCode = 1;

Derselbe Code, ein Wort anders. Hier wird die Zahl nur hinterlegt. Node arbeitet ab, was noch offen ist, und benutzt sie dann beim regulären Ende. Der Timeout kommt dran, die Ausgabe ist vollständig, und trotzdem ist der Exit-Code 1.

Ich nehme im Zweifel process.exitCode, weil es mir nichts abschneidet.

process.exit() ist dann richtig, wenn du wirklich sofort weg willst. Etwa bei einem Fehler ganz am Anfang, wenn ein Pflichtargument fehlt und noch gar nichts läuft. So ein Fall stand in der Aufgabe zu Lektion 4.1, und dort passt process.exit(1) auch.

Zwei getrennte Ausgabekanäle

Zahl und Kanal gehören zusammen. Die Zahl sagt einem Skript, dass etwas schiefging, und eine Zeile auf dem Fehlerkanal sagt dem Menschen, was.

Ein Prozess hat zwei Ausgabekanäle. console.log schreibt auf stdout, die Standardausgabe. console.error schreibt auf stderr, den Fehlerkanal. In einer Shell landen beide untereinander auf dem Bildschirm, und man sieht keinen Unterschied.

Zwei Kanäle nebeneinander
console.log("Ergebnis: 42 Zeilen");
console.error("Hinweis: 2 Dateien übersprungen");
console.log("Fertig.");

Die drei Zeilen laufen über zwei Kanäle. „Ergebnis: 42 Zeilen“ und „Fertig.“ gehen auf stdout, der Hinweis dazwischen auf stderr. Im Terminal hier steht jeder Kanal in einem eigenen Block, stderr in Rot. Eine Shell auf deinem Rechner macht das nicht. Dort steht der Hinweis zwischen den beiden anderen Zeilen und sieht genauso aus. Ein anderes Programm bekommt die Kanäle trotzdem getrennt zu fassen.

Was die Trennung bringt, siehst du an einer Umleitung.

node bericht.mjs > ergebnis.txt

In der Datei landen nur die beiden stdout-Zeilen. Der Hinweis bleibt auf dem Bildschirm, wo du ihn siehst.

Mit dieser Trennung baut ein Programm einen ganzen Bericht, ohne dass ein Fortschrittssatz darin landet.

Ein Bericht, der in eine Datei will
// So sieht ein Werkzeug aus, das seine Trennung ernst nimmt. Gestartet
// wird es mit:  node bericht.mjs > bericht.html 2> lauf.log
const dateien = [
  { name: "januar.csv", saetze: 1204, fehler: 0 },
  { name: "februar.csv", saetze: 987, fehler: 3 },
  { name: "maerz.csv", saetze: 1130, fehler: 0 },
];

// Der Ablauf. Gehoert dem Menschen davor, also stderr.
dateien.forEach((d, i) => {
  console.error(`Lese ${d.name} (${i + 1} von ${dateien.length})`);
});

// Das Ergebnis. Gehoert in die Datei, also stdout.
console.log("<h1>Auswertung Q1</h1>");
console.log("<table>");
console.log("<tr><th>Datei</th><th>Sätze</th><th>Fehler</th></tr>");
for (const d of dateien) {
  console.log(`<tr><td>${d.name}</td><td>${d.saetze}</td><td>${d.fehler}</td></tr>`);
}
console.log("</table>");

console.error("Fertig, 3 Dateien.");

Das Programm schreibt seinen Fortschritt auf stderr und den fertigen Bericht auf stdout, sonst nichts. Im Terminal stehen beide getrennt, das Markup für sich und die vier Zeilen über den Ablauf in Rot. Der Reiter Browser bleibt dabei leer. Hier läuft kein Server, also gibt es nichts, was ein Browser laden könnte. Wohin das Markup geht, siehst du erst, wenn es in einer Datei landet.

Auf deinem eigenen Rechner täte > bericht.html dasselbe wie hier. Den Aufruf aus dem Kommentar über dem Code findest du in der Befehlsleiste: node bericht.mjs > bericht.html 2> lauf.log.

Der Befehl schweigt, beide Kanäle sind ja umgeleitet. Danach zeigt ls drei Dateien statt einer, cat lauf.log die vier Ablaufzeilen und head -2 bericht.html den Anfang des Berichts, <h1>Auswertung Q1</h1> und <table>.

Dasselbe gilt für eine Kette. node erzeuge.mjs | node verarbeite.mjs reicht nur stdout weiter, und was du auf stderr schreibst, stört die Kette nicht.

Was wohin gehört

Auf stdout gehört das Ergebnis, also das, wofür dein Programm aufgerufen wurde: die umgerechnete Zahl, die erzeugte Liste, das JSON. Auf stderr gehört alles über den Ablauf: Fortschrittsmeldungen, Warnungen, Fehler, „lese Datei 3 von 40“. Für den Menschen vor dem Bildschirm ist das nützlich, aber in einer Datei will es niemand haben.

Ich prüfe das mit einer Umleitung im Kopf. Was in der Datei stehen soll, wenn jemand meine Ausgabe umleitet, gehört auf stdout, der Rest nicht.

Ein Fehler dabei fällt lange nicht auf, weil auf dem Bildschirm ja alles da ist. Er fällt erst auf, wenn jemand dein Werkzeug zum ersten Mal in ein Skript einbaut, und dann steht mitten in der erzeugten Datei „Verarbeite Datei 3 von 40“.

Das Prüfwerkzeug in der Aufgabe meldet sich noch auf dem falschen Kanal und mit der falschen Zahl.

Zum Mitnehmen

0 heißt erfolgreich, jede andere Zahl nicht, und process.exitCode setzt die Zahl, ohne das Programm abzuschneiden. Das Ergebnis geht auf stdout, alles über den Ablauf auf stderr, und eine Umleitung mit > fängt nur stdout ein.

Jetzt du

Basis Konto, kostenlos

Zu 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 4 Beispielen zum Ausprobieren

    Steht hier, ohne Konto lesbar.

  • Aufgabe, dein Code läuft auf einem Server

    Öffnet sich mit dem Basis Konto.