Schreiben von Protokollen auf Standardausgabe und Fehler

In Code Engine werden von Ihrem Workload ausgegebene Protokolleinträge nur dann gesammelt, wenn sie in stdout oder stderr geschrieben werden, wobei die Richtlinien der Zwölf-Faktoren-App befolgt werden, die empfehlen, Protokolle als Ereignisströme zu behandeln, anstatt Protokolldateien zu verwalten. Siehe Erstellen von Cloud-nativen Anwendungen: 12-Faktoren-Anwendungen - Faktor 11 - Protokolle.

Die Protokollierungspipeline der Plattform erfasst und verarbeitet diesen Output automatisch und macht ihn für die Analyse und Fehlerbehebung verfügbar. Protokollzeilen, die in Dateien im ephemeren Dateisystem des Containers geschrieben werden, werden nicht aufgenommen, persistiert oder über die Protokollierungsschnittstelle angezeigt. Folglich gehen alle im ephemeren Dateisystem gespeicherten Protokolle verloren, wenn die Instanz neu gestartet oder beendet wird, und stehen nicht für die Fehlersuche im Betrieb oder die Ursachenanalyse zur Verfügung.

Sollte ich meine Protokollzeilen mit Zeitstempeln versehen?

Von Benutzer-Workloads erzeugte Protokolldatensätze sollten keine eigenen Zeitstempelinformationen einbetten, da die Code Engine Infrastruktur Zeitstempel automatisch erfasst und standardisiert. Die Einbeziehung von Zeitstempeln auf Anwendungsebene kann zu Inkonsistenzen zwischen den Diensten führen, insbesondere wenn Arbeitslasten in verteilten oder containerisierten Umgebungen ausgeführt werden, in denen die Systemuhren abweichen oder sich verschieben können. Durch die Verwendung der Zeitstempel der Plattform werden einheitliche Zeitformate, eine genaue Abfolge und eine zuverlässige Korrelation mit anderen systemgenerierten Protokollen gewährleistet, was die Fehlerbehebung, die Prüfung und die Beobachtbarkeit in der gesamten Bereitstellung vereinfacht.

Wie werden meine Protokollstufen dem Schweregrad IBM Cloud Logs zugeordnet?

Die in jedem Protokolleintrag angegebene Protokollstufe wird den IBM Cloud Logs Schweregraden zugeordnet, wie in Zuordnung von Protokollschweregraden zu IBM Cloud Logs Schweregraden beschrieben. In den folgenden Abschnitten erfahren Sie mehr darüber, wie die Protokollebenen für unstrukturierte und strukturierte Protokolle geparst werden und welche Protokollebenenwerte unterstützt werden.

Was ist, wenn meine Protokolldaten mehrzeilig sind?

Um die Vorteile der Such- und Formatierungsfunktionen von IBM Cloud Logs zu nutzen, ändern Sie Ihre Protokollformatierung wie folgt.

• Wenn sich Ihre Protokollzeilen über mehrere Zeilen erstrecken, sollten Sie die Formatierung und Ausgabe der Protokolle so ändern, dass sie in einer einzigen Zeile stehen. Verwenden Sie das JSONL-Format (siehe Protokollformate ) für Ihre Protokolle mit IBM Cloud Logs.
• Ihre Protokolle müssen den Grenzwerten für IBM Cloud Logs entsprechen.

Beispiele

Im Folgenden finden Sie einfache Beispiele, die eine unstrukturierte Protokollzeile (Freiformtext) in die Standardausgabe schreiben.

Die Beispiele sind im öffentlichen Beispiel-Repository Code Engine unter https://github.com/IBM/CodeEngine/blob/main/logging/README.md veröffentlicht.

Node.js (JavaScript)

console.log('User signup succeeded for account abc123');

Python

print("User signup succeeded for account abc123")

Golang

package main

import (
    "fmt"
)

func main() {
    fmt.Println("User signup succeeded for account abc123")
}

Java

package com.ibm.cloud.codeengine.sample;

public class App {
    public static void main(String[] args) {
        System.out.println("User signup succeeded for account abc123");
    }
}

Erkennung des Loglevels

Jeder Protokolleintrag wird nach Schlüsselwörtern durchsucht, um den Schweregrad zu bestimmen. Die Schweregrade, die fallunsensitiv bewertet werden, sind critical, error, warn, info, debug und verbose.

Wenn eine Protokollzeile mit einem Schweregrad-Schlüsselwort im Format LEVEL MESSAGE beginnt, entfernt Code Engine den erkannten Schweregrad aus der angezeigten Protokollmeldung, damit sich die Benutzer auf den Kerninhalt konzentrieren können, während sie in der Ansicht IBM Cloud Logs weiterhin genau nach Schweregrad filtern können. In diesem Fall wird der extrahierte Schweregradwert im Feld level des Protokollsatzes gespeichert. Die folgenden von der Groß- und Kleinschreibung unabhängigen Schweregrade werden unterstützt: fatal, error, warn, info, debug, und trace. In Node.js könnten Sie zum Beispiel schreiben:

// Unstructured log with level prefix
console.log('ERROR Payment service timeout while creating invoice');

In IBM Cloud Logs erscheint dieser Eintrag mit dem Schweregrad Fehler und dem Meldungstext "Zeitüberschreitung des Zahlungsdienstes beim Erstellen der Rechnung "; Sie können dann nach Schweregrad = Fehler filtern, um die Ergebnisse einzugrenzen. Sie können auch Parsing- und Schweregradregeln verwenden, um die Extraktion und den Abgleich von Ebenen für Ihre Umgebung anzupassen.

Die Erkennung der Log-Ebene funktioniert auch, wenn die Log-Zeilen leicht unterschiedliche Formate haben, wie z.B. LEVEL: MESSAGE oder [LEVEL] MESSAGE. In diesen Fällen wird das Schlüsselwort "level" jedoch nicht aus der Protokollmeldung entfernt, obwohl der Schweregrad noch immer richtig eingestuft ist.

Außerdem kann die Erkennungslogik einen Schweregrad ableiten, wenn ein unterstütztes Schlüsselwort an beliebiger Stelle in der Nachricht erscheint, nicht nur am Anfang. Zum Beispiel die Protokollzeile:

The payment workflow encountered an unexpected error during validation

Diese Protokollzeile wird als Fehler eingestuft, da das Wort Fehler im Meldungstext erscheint.

Die Erkennung der Protokollierungsstufe berücksichtigt nicht den Eingangsstrom (stdout oder stderr) für die Erkennung der Protokollierungsstufe. Daher werden Protokollmeldungen, die in den Standardfehler (stderr) geschrieben werden, nur anhand des Meldungstextes ausgewertet. Zum Beispiel wird console.error("Some message") als Info eingestuft, obwohl es auf stderr geschrieben wird.

Bei Funktions-Workloads wird die Protokollebene nicht aus der angezeigten Protokollmeldung entfernt, selbst wenn sie am Anfang der Protokollzeile im Format LEVEL MESSAGE erkannt wird.

Parsing und Auswertung von Zeitstempeln

Das Hinzufügen von Zeitstempeln zu den Anwendungsprotokollzeilen wird nicht empfohlen, da Code Engine beim Einlesen der Protokolle automatisch einen normalisierten Zeitstempel zuweist. Wenn ein Zeitstempel am Anfang einer Protokollzeile steht, versucht das System, ihn zu analysieren. Wenn er mit einem der unterstützten Formate übereinstimmt, wird der Zeitstempel aus der angezeigten Protokollmeldung entfernt, ähnlich wie bei der Behandlung von Protokollebenen. Folgende Zeitstempelformate werden unterstützt:

• 2026-02-08T20:30:45.123
• 2026-02-08T20:30:45.123Z
• 2026-02-08T21:03:45.123456Z
• 2026-02-08T21:03:45.123456789Z
• 2026-02-08 21:03:45.123Z
• 2026-02-08 20:30:45.123

Wenn eine Protokollzeile am Anfang sowohl einen Zeitstempel als auch eine Protokollstufe enthält (z. B. TIMESTAMP LEVEL MESSAGE), wertet die Pipeline beide Felder aus. Wenn beide mit den unterstützten Mustern übereinstimmen, werden sie entsprechend klassifiziert und aus der gerenderten Protokollnachricht entfernt, so dass nur der Nachrichtentext zum leichteren Lesen und Filtern übrig bleibt. Zum Beispiel werden die folgenden Formate erfolgreich analysiert:

• 2026-02-08T21:03:45.123456789Z ERROR Payment service timeout
• 2026-02-08 20:30:45.123 INFO Starting billing workflow

In Fällen, in denen ein Zeitstempel auftaucht, aber nicht mit den unterstützten Formaten übereinstimmt, bleibt er Teil der Protokollzeile und wird als normaler Text behandelt, aber der Rest der Nachricht wird weiterhin normal verarbeitet.

Bei Funktions-Workloads werden Zeitstempel nicht geparst, ausgewertet oder aus Protokollnachrichten entfernt. Jeder in den Funktionsprotokollen enthaltene Zeitstempel bleibt Teil der angezeigten Meldung.

Unterstützung für mehrere Leitungen

Code Engine unterstützt mehrzeilige Protokolleinträge. Bei der Ausgabe von Protokollen müssen Sie jedoch sicherstellen, dass Zeilenumbrüche (\n) ordnungsgemäß kodiert sind (\\n), damit die Protokollierungspipeline mehrzeilige Meldungen korrekt verarbeiten und darstellen kann. In Node.js können Sie zum Beispiel einen mehrzeiligen Protokolleintrag wie diesen erstellen:

console.log("Starting billing workflow...\\nStep 1: Validating input...\\nStep 2: Processing payment...");

Fehler protokollieren

Wenn Ihre Workload mehrzeilige Fehler-Stacktraces ausgibt, verwenden Sie das strukturierte JSON-Protokollformat anstelle der unstrukturierten Konsolenausgabe. Strukturierte Protokolle bewahren mehrzeilige Felder zuverlässig und stellen sicher, dass Stack Traces in einem einzigen Protokolleintrag gruppiert werden (siehe Abschnitt Strukturierte Protokolle ).

Die folgende Protokollmeldung wird beispielsweise als Fehler eingestuft, da das Schlüsselwort "error" in der Protokollmeldung erscheint. Der Stack-Trace, der vom err Objekt bereitgestellt wird, wird jedoch in mehreren Protokollzeilen dargestellt.

try {
  throw new Error("boom!");
} catch (err) {
  console.error("An error occurred", err);
}

Beispiele

Es folgen minimale strukturierte Protokollierungsbeispiele für jede Sprache und Laufzeit, die ein einzelnes JSON mit der Protokollstufe im Feld level und der Protokollmeldung im Feld message ausgeben.

Die Beispiele sind im öffentlichen Beispiel-Repository Code Engine unter https://github.com/IBM/CodeEngine/blob/main/logging/README.md veröffentlicht.

Node.js ( winston )

import winston from "winston";
const { combine, json } = winston.format;

// Create a custom logger
const logger = winston.createLogger({
  level: 'info',
  transports: [new winston.transports.Console()],
  format: combine(json())
});

// Usage
logger.info("User signup succeeded")
logger.error("Payment service timeout")

Python ( Loguru )

from loguru import logger
import sys
import json
import traceback

# Define a custom JSON sink
def json_sink(message):
    record = message.record

    # Base fields: level + message, no timestamp
    payload = {
        "level": record["level"].name,   # e.g., "INFO"
        "message": record["message"],    # rendered message
    }

    # Merge in any bound extra fields as top-level keys
    # (skip reserved keys to avoid accidental overwrite)
    for k, v in record["extra"].items():
        if k not in ("level", "message", "stack"):
            payload[k] = v

    # If an exception is attached, render full stack trace into "stack"
    exc = record["exception"]
    if exc:
        # exc.type, exc.value, exc.traceback are available from Loguru
        stack_text = "".join(traceback.format_exception(exc.type, exc.value, exc.traceback))
        payload["stack"] = stack_text

    # Emit a single JSON line
    sys.stdout.write(json.dumps(payload, ensure_ascii=False) + "\n")
    sys.stdout.flush()


# Remove default handler (which includes timestamp, etc.) and add our custom sink
logger.remove()
logger.add(json_sink, level="DEBUG")  # lowest level you want to capture

# Usage
logger.info("User signup succeeded")
logger.error("Payment service timeout")

Golang ( slog )

package main

import (
    "log/slog"
    "os"
)

func main() {
    handler := slog.NewJSONHandler(os.Stdout, &slog.HandlerOptions{
        // Remove time and rename msg->message
        ReplaceAttr: func(groups []string, attr slog.Attr) slog.Attr {
            // Drop the time attribute
            if attr.Key == slog.TimeKey {
                return slog.Attr{} // empty => removed
            }
            // Rename msg to message
            if attr.Key == slog.MessageKey {
                return slog.String("message", attr.Value.String())
            }
            return attr
        },
    })
    logger := slog.New(handler)

    // Usage
    logger.Info("User signup succeeded")
    logger.Error("Payment service timeout")
}

Java ( SLF4J und Logback mit logstash-logback-encoder )

src/main/resources/logback.xml:

<configuration>
    <appender name="jsonConsoleAppender" class="ch.qos.logback.core.ConsoleAppender">
        <encoder class="net.logstash.logback.encoder.LogstashEncoder">
            <timeZone>UTC</timeZone>
            <fieldNames>
                <timestamp>[ignore]</timestamp>
                <logger>[ignore]</logger>
                <version>[ignore]</version>
                <levelValue>[ignore]</levelValue>
                <threadName>[ignore]</threadName>
            </fieldNames>
        </encoder>
    </appender>

    <root level="DEBUG">
        <appender-ref ref="jsonConsoleAppender" />
    </root>
</configuration>

src/main/java/com/ibm/cloud/codeengine/sample/App.java:

package com.ibm.cloud.codeengine.sample;

import org.slf4j.Logger;
import org.slf4j.LoggerFactory;

public class App {
  private static final Logger logger = LoggerFactory.getLogger(App.class);

  public static void main(String[] args) {
    logger.info("User signup succeeded");
    logger.error("Payment service timeout");
  }
}

Erkennung des Loglevels

Jeder Protokolleintrag wird nach Schlüsselwörtern durchsucht, um den Schweregrad zu bestimmen. Die Schweregrade, die fallunsensitiv bewertet werden, sind critical, error, warn, info, debug und verbose.

Wenn Sie strukturierte Protokolle verwenden, erkennt Code Engine automatisch die Protokollebene, wenn sie in einem der folgenden Felder angegeben wird: level, severity, oder logLevel. Der Wert in diesen Feldern ist unabhängig von der Groß- und Kleinschreibung, d. h. Einträge wie error, ERROR oder Error entsprechen alle demselben Schweregrad. Die folgenden von der Groß- und Kleinschreibung unabhängigen Schweregrade werden unterstützt: critical, error, warn, info, debug, und verbose. Wenn ein unterstütztes Feld vorhanden ist und einen dieser Werte enthält, wird die Protokollstufe extrahiert, normalisiert und für die Filterung und Kategorisierung in der Benutzeroberfläche für Protokolle verwendet. Die folgenden strukturierten Protokollzeilen werden beispielsweise alle korrekt mit der Stufe Fehler interpretiert:

{ "level": "error", "message": "Payment service timeout" }
{ "severity": "ERROR", "message": "Failed to connect to database" }
{ "logLevel": "eRrOr", "message": "Workflow aborted" }

Unabhängig von der Großschreibung oder dem spezifischen Feldwert identifiziert die Plattform die Protokollebene korrekt und wendet sie zum Filtern, Gruppieren und Analysieren Ihrer strukturierten Protokolldaten an.

Auswertung des Zeitstempels

Bei strukturierten Protokollen werden benutzerdefinierte Zeitstempel nicht geparst oder ausgewertet. Alle Zeitstempelfelder, die Sie angeben, werden als reine Nutzdaten behandelt, während die Plattform immer ihren eigenen Aufnahmezeitstempel für die Ordnung und Filterung verwendet.

Im folgenden Beispiel wird der Wert "timestamp" beibehalten, aber für die Protokollierung ignoriert.

{ "level": "INFO", "message": "Processing started", "timestamp": "2026-02-08T20:30:45.123Z" }

Hinzufügen zusätzlicher Kontextinformationen

Sie können strukturierte Protokolle mit benutzerdefinierten Feldern anreichern (z. B. requestId, userId oder domänenspezifische Metadaten). Nachfolgend finden Sie Minimalbeispiele für jeden zuvor verwendeten Stapel.

Halten Sie benutzerdefinierte Felder kurz und stabil (z. B. IDs, Codes oder kleine Enums), um die Filterbarkeit zu maximieren und die Kardinalität in Ihrer Protokollierungsinstanz zu minimieren.

Node.js ( winston )

logger.debug("A structured log entry that contains an extra key", {
  extra_key: "extra_value",
});

Python ( Loguru )

logger.bind(extra_key="extra_value").debug("A structured log entry that contains an extra key")

Golang ( slog )

logger.Debug("A structured log entry that contains an extra key",
  slog.String("extra_key", "extra_value"),
)

Java ( SLF4J und Logback mit logstash-logback-encoder )

logger.atDebug().addKeyValue("extra_key", "extra_value")
                .log("A structured log entry that contains an extra key");

Fehler protokollieren

Um sowohl die Fehlermeldung als auch die Stapelverfolgung in strukturierten Protokollen zu erfassen, geben Sie einen JSON-Datensatz aus, der Ihre Standardfelder (level, message) sowie ein stack (oder ein ähnliches) Feld enthält.

Node.js ( winston )

// Error logging
try {
  throw new Error("boom!");
} catch (err) {
  // The error stack trace is rendered in a single log message (see field stack)
  logger.error("An error occurred", err);
}

Python ( Loguru )

try:
  raise RuntimeError("boom!")
except Exception:
  # logger.exception() automatically attaches the current exception info
  logger.exception("An error occurred")

Golang ( slog )

err := errors.New("boom!")
logger.Error("An error occurred",
    slog.Any("err", err),
    // The error stack trace is rendered in a single log message (see field stack)
    slog.String("stack", string(debug.Stack())),
)

Java ( SLF4J und Logback mit logstash-logback-encoder )

try {
    throw new RuntimeException("boom!");
} catch (Exception e) {
    logger.atError()
            .setCause(e) // The error stack trace is rendered in a single log message (see field stack_trace)
            .log("An error occurred");
}

Funktions-Workloads verarbeiten mehrzeilige Protokolle, aber jedes Zeilenumbruchzeichen führt zu einem separaten Protokolleintrag. Bei der Protokollierung von Stack Traces mit strukturierten Logging-Frameworks müssen Sie möglicherweise Zeilenumbrüche manuell ausblenden, um sicherzustellen, dass sie ordnungsgemäß als ein einzelner Protokolleintrag dargestellt werden.

Kann ich Filter auf IBM Cloud Logs Daten anwenden?

Sie können den Filter modifizieren und erweitern, um Protokolldaten auf einer bestimmten Ebene oder auf einer detaillierteren Ebene für eine bestimmte Anwendungsrevision, einen Joblauf oder einen Build-Lauf auf der Seite IBM Cloud Logs anzuzeigen, je nach Bedarf.

• Wenn app:"codeengine" eingestellt ist, werden nur die Protokolle von Code Engine angezeigt.

• Wenn codeengine.project:'<project_name>' eingestellt ist, werden nur Protokolle von einem bestimmten Projekt angezeigt.

• Wenn codeengine.component:'<your_component_name>' gesetzt ist, werden nur Protokolle der angegebenen Komponente (Anwendung, Job oder Build) angezeigt. Wenn Ihre Code Engine Komponenten den gleichen Namen haben, schließt der Filter die Protokolle dieser Komponenten ein. Beispiel:

  • Der Filter app:"codeengine" AND codeengine.component:"myapp" beschränkt die Protokolle auf die Anwendungsebene myapp.
  • Der Filter app:"codeengine" AND codeengine.subcomponent:"myapp\-00002" beschränkt die Protokolle auf die Anwendungsrevisionsebene myapp-0002.
  • Mit dem Filter app:"codeengine" AND codeengine.component:"myjob" werden die Protokolle auf die spezifische Auftragsebene myjob eingeschränkt.
  • Der Filter app:"codeengine" AND codeengine.subcomponent:"myjob\-jobrun\-t6m7l" beschränkt die Protokolle auf die spezifische Ebene des myjob-jobrun-t6m7l Joblaufs.
  • Der Filter app:"codeengine" AND codeengine.component:"mybuild" beschränkt die Protokolle auf die spezifische mybuild build level.
  • Der Filter app:"codeengine" AND codeengine.subcomponent:"mybuild\-run\-121212" beschränkt die Protokolle auf den spezifischen mybuild-run-121212 build run level.

Weitere Informationen zum Konfigurieren und Starten der Protokollierung in der Konsole finden Sie unter Anzeigen von Anwendungs-, Auftrags- oder Funktionsprotokollen über die Konsole.