Écriture des journaux sur la sortie standard et sur l'erreur

Dans Code Engine, les enregistrements de journaux émis par votre charge de travail ne sont collectés que lorsqu'ils sont écrits sur stdout ou stderr, conformément aux lignes directrices de l'application Twelve-Factor qui recommandent de traiter les journaux comme des flux d'événements plutôt que de gérer des fichiers journaux. Voir Création d'applications cloud-natives : applications à 12 facteurs - Facteur 11 - Logs.

Le pipeline de journalisation de la plateforme capture et traite automatiquement cette sortie, la rendant disponible pour l'analyse et le dépannage. Les lignes de journal écrites dans les fichiers du système de fichiers éphémère du conteneur ne sont pas ingérées, persistées ou exposées par l'interface de journalisation. Par conséquent, les journaux stockés sur le système de fichiers éphémères sont perdus lorsque l'instance est redémarrée ou arrêtée et ne sont pas disponibles pour le débogage opérationnel ou l'analyse des causes profondes.

Dois-je ajouter des horodatages à mes lignes de journal?

Les enregistrements de journaux générés par les charges de travail des utilisateurs doivent éviter d'intégrer leurs propres informations d'horodatage, car l'infrastructure Code Engine capture et normalise automatiquement les horodatages. L'inclusion d'horodatages au niveau de l'application peut créer des incohérences entre les services, en particulier lorsque les charges de travail s'exécutent dans des environnements distribués ou conteneurisés où les horloges des systèmes peuvent dériver ou différer. L'utilisation des horodatages de la plateforme garantit des formats horaires uniformes, un séquençage précis et une corrélation fiable avec d'autres journaux générés par le système, ce qui simplifie le dépannage, l'audit et l'observabilité dans l'ensemble du déploiement.

Comment mes niveaux de journalisation correspondent-ils à la gravité IBM Cloud Logs?

Le niveau de journalisation indiqué dans chaque enregistrement est mis en correspondance avec les niveaux de gravité de IBM Cloud Logs, tels que décrits à l'adresse Mappage des sévérités du journal aux sévérités de IBM Cloud Logs. Dans les sections suivantes, vous apprendrez comment les niveaux de journalisation sont analysés pour les journaux non structurés et structurés et quelles sont les valeurs de niveau de journalisation prises en charge.

Que se passe-t-il si mes données d'enregistrement sont multilignes?

Pour profiter des fonctions de recherche et de formatage de IBM Cloud Logs, modifiez le formatage de votre journal comme suit.

• Si vos lignes de journal s'étendent sur plusieurs lignes, modifiez la façon dont vous formatez et produisez vos journaux afin qu'ils ne forment qu'une seule ligne. Utilisez le format JSONL (voir Formats des journaux ) pour vos journaux avec IBM Cloud Logs.
• Vos grumes doivent être conformes aux limites fixées pour IBM Cloud Logs.

Exemples

Vous trouverez ci-dessous des exemples simples qui écrivent une ligne de journal non structurée (texte libre) sur la sortie standard.

Les exemples sont publiés dans le dépôt d'échantillons public Code Engine à l'adresse https://github.com/IBM/CodeEngine/blob/main/logging/README.md.

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");
    }
}

Détection du niveau de journalisation

Chaque enregistrement est analysé à la recherche de mots-clés afin de déterminer le degré de gravité. Les valeurs de gravité, qui sont évaluées de manière insensible à la casse, sont critical, error, warn, info, debug, et verbose.

Si une ligne de journal commence par un mot-clé de gravité au format LEVEL MESSAGE, Code Engine supprime le niveau détecté du message de journal affiché afin que les utilisateurs puissent se concentrer sur le contenu principal tout en continuant à filtrer précisément par gravité dans la vue IBM Cloud Logs. Dans ce cas, la valeur de gravité extraite est stockée dans le champ de l'enregistrement level. Les niveaux de gravité suivants, insensibles à la casse, sont pris en charge : fatal, error, warn, info, debug, et trace. Par exemple, à l'adresse Node.js, vous pouvez écrire :

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

Dans IBM Cloud Logs, cette entrée apparaît avec la gravité Error et le texte du message "Payment service timeout while creating invoice "; vous pouvez alors filtrer par Severity = Error pour restreindre les résultats. Vous pouvez également utiliser des règles d'analyse et de gravité pour adapter la manière dont les niveaux sont extraits et mis en correspondance à votre environnement.

La détection du niveau de journalisation fonctionne également lorsque les lignes de journalisation suivent des formats légèrement différents, tels que LEVEL: MESSAGE ou [LEVEL] MESSAGE. Toutefois, dans ces cas, le mot-clé level est supprimé du message d'enregistrement ( pas ), même si la gravité est toujours correctement classée.

En outre, la logique de détection peut déduire un niveau de gravité lorsqu'un mot-clé pris en charge apparaît n'importe où dans le message, et pas seulement au début. Par exemple, la ligne de journal :

The payment workflow encountered an unexpected error during validation

Cette ligne de journal est classée dans la catégorie " Erreur " parce que le mot " erreur" apparaît dans le texte du message.

La détection du niveau de journalisation ne prend pas en compte le flux d'entrée (stdout ou stderr) pour la détection du niveau de journalisation. Par conséquent, les messages écrits sur l'erreur standard (stderr) sont évalués uniquement sur la base du texte du message. Par exemple, console.error("Some message") est classé comme Info, bien qu'il soit écrit sur stderr.

Pour les charges de travail fonctionnelles, le niveau du journal n'est pas supprimé du message affiché, même s'il est détecté au début de la ligne de journal dans le format LEVEL MESSAGE.

Analyse et évaluation de l'horodatage

L'ajout d'un horodatage aux lignes des journaux d'application est non recommandé car Code Engine attribue automatiquement un horodatage normalisé lors de l'ingestion des journaux. Si un horodatage est inclus au début d' une ligne de journal, le système tente de l'analyser. S'il correspond à l'un des formats pris en charge, l'horodatage est supprimé du message d'enregistrement affiché, de la même manière que les niveaux d'enregistrement sont gérés. Les formats d'horodatage pris en charge sont les suivants

• 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

Lorsqu'une ligne de journal contient à la fois un horodatage et un niveau de journal au début (par exemple, TIMESTAMP LEVEL MESSAGE), le pipeline évalue les deux champs. Si les deux correspondent aux modèles pris en charge, ils sont classés de manière appropriée et supprimés du message rendu, ne laissant que le corps du message pour faciliter la lecture et le filtrage. Par exemple, les formats suivants sont analysés avec succès :

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

Dans les cas où un horodatage apparaît mais ne correspond pas aux formats pris en charge, il reste dans la ligne de journal et est traité comme du texte normal, mais le reste du message est toujours traité normalement.

Pour les charges de travail fonctionnelles, les horodatages ne sont pas analysés, évalués ou supprimés des messages du journal. Tout horodatage inclus dans les journaux de fonctions reste dans le message affiché.

Support multiligne

Code Engine prend en charge les entrées de journal sur plusieurs lignes. Cependant, lorsque vous émettez des journaux, vous devez vous assurer que les caractères de nouvelle ligne (\n) sont correctement encodés (\\n) afin que le pipeline de journalisation puisse traiter et rendre correctement les messages multi-lignes. Par exemple, à l'adresse Node.js, vous pouvez produire une entrée de journal multi-lignes comme celle-ci :

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

Enregistrement des erreurs

Si votre charge de travail émet des traces d'erreur sur plusieurs lignes, utilisez le format de journal JSON structuré au lieu de la sortie console non structurée. Les journaux structurés préservent les champs multilignes de manière fiable et garantissent que les traces de pile sont regroupées dans un seul enregistrement, ce qui est abordé dans la section Journaux structurés.

Par exemple, le message suivant est classé dans la catégorie Erreur car le mot-clé "error" apparaît dans le message. Cependant, la trace de la pile fournie par l'objet err est présentée sous la forme de plusieurs lignes de journal.

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

Exemples

Voici exemples d'enregistrements structurés minimaux pour chaque langue et exécution qui émet un seul JSON avec le journal niveau dans le champ level et le journal message dans le champ message.

Les exemples sont publiés dans le dépôt d'échantillons public Code Engine à l'adresse https://github.com/IBM/CodeEngine/blob/main/logging/README.md.

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 et Logback avec 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");
  }
}

Détection du niveau de journalisation

Chaque enregistrement est analysé à la recherche de mots-clés afin de déterminer le degré de gravité. Les valeurs de gravité, qui sont évaluées de manière insensible à la casse, sont critical, error, warn, info, debug, et verbose.

Lorsque vous utilisez des journaux structurés, Code Engine détecte automatiquement le niveau du journal lorsqu'il est indiqué dans l'un des champs suivants : level, severity, ou logLevel. La valeur de ces champs n'est pas sensible à la casse, ce qui signifie que des entrées telles que error, ERROR ou Error correspondent toutes à la même gravité. Les niveaux de gravité suivants, insensibles à la casse, sont pris en charge : critical, error, warn, info, debug, et verbose. Lorsqu'un champ pris en charge est présent et contient l'une de ces valeurs, le niveau du journal est extrait, normalisé et utilisé pour le filtrage et la catégorisation dans l'interface utilisateur des journaux. Par exemple, les lignes de journal structurées suivantes sont toutes correctement interprétées avec le niveau Erreur:

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

Indépendamment de la capitalisation ou de la valeur spécifique du champ utilisé, la plateforme identifie correctement le niveau du journal et l'applique pour le filtrage, le regroupement et l'analyse de vos données de journal structurées.

Évaluation de l'horodatage

Pour les journaux structurés, les horodatages personnalisés ne sont pas analysés ou évalués. Tout champ d'horodatage que vous fournissez est traité purement comme des données utiles, tandis que la plateforme applique toujours son propre horodatage d'ingestion pour l'ordonnancement et le filtrage.

Dans l'exemple ci-dessous, la valeur "timestamp" est conservée mais ignorée pour la synchronisation du journal.

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

Ajout d'informations contextuelles supplémentaires

Vous pouvez enrichir les journaux structurés avec des champs personnalisés (par exemple, requestId, userId, ou des métadonnées spécifiques à un domaine). Les exemples suivants sont des exemples minimaux pour chaque pile utilisée précédemment.

Les champs personnalisés doivent être concis et stables (par exemple, des identifiants, des codes ou de petites listes) afin de maximiser les possibilités de filtrage et de minimiser la cardinalité dans votre instance de journalisation.

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 et Logback avec logstash-logback-encoder )

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

Enregistrement des erreurs

Pour capturer à la fois le message d'erreur et sa trace de pile dans des journaux structurés, émettez un enregistrement JSON qui comprend vos champs standard (level, message) plus un champ stack (ou similaire).

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 et Logback avec 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");
}

Les charges de travail fonctionnelles gèrent des journaux multilignes, mais chaque caractère de retour à la ligne donne lieu à une entrée de journal distincte. Lorsque vous enregistrez des traces de pile avec des structures d'enregistrement structurées, vous pouvez avoir besoin d'échapper manuellement les caractères de nouvelle ligne pour vous assurer qu'ils sont rendus correctement comme une entrée d'enregistrement unique.

Puis-je appliquer des filtres aux données de IBM Cloud Logs?

Vous pouvez modifier et étendre le filtre pour afficher les données de journal à un niveau spécifique ou à un niveau plus granulaire pour une révision d'application spécifique, une exécution de travail ou une exécution de construction à partir de la page IBM Cloud Logs, en fonction de vos besoins.

• Si l'option app:"codeengine" est activée, seuls les journaux Code Engine sont affichés.

• Si l'option codeengine.project:'<project_name>' est activée, seuls les journaux d'un projet spécifique sont affichés.

• Si codeengine.component:'<your_component_name>' est défini, seuls les journaux du composant spécifié (application, job ou build) sont affichés. Si vos composants Code Engine portent le même nom, le filtre inclut les journaux de ces composants. Par exemple :

  • Le filtre app:"codeengine" AND codeengine.component:"myapp" limite les journaux au niveau de l'application myapp.
  • Le filtre app:"codeengine" AND codeengine.subcomponent:"myapp\-00002" limite les journaux au niveau de révision de l'application myapp-0002.
  • Le filtre app:"codeengine" AND codeengine.component:"myjob" permet de limiter les journaux au niveau de travail spécifique de myjob.
  • Le filtre app:"codeengine" AND codeengine.subcomponent:"myjob\-jobrun\-t6m7l" permet de limiter les journaux au niveau d'exécution spécifique de la tâche myjob-jobrun-t6m7l.
  • Le filtre app:"codeengine" AND codeengine.component:"mybuild" permet de limiter les journaux au niveau de construction spécifique de mybuild.
  • Le filtre app:"codeengine" AND codeengine.subcomponent:"mybuild\-run\-121212" permet de limiter les journaux au niveau d'exécution spécifique de mybuild-run-121212.

Pour plus d'informations sur la configuration et le démarrage de la journalisation dans la console, voir Afficher les journaux d'applications, de tâches ou de fonctions à partir de la console.