Scrivere e visualizzare i log per le applicazioni, i lavori e le funzioni

Scrittura dei log su standard output ed errore

In Code Engine, i record di log emessi dal carico di lavoro vengono raccolti solo quando vengono scritti in stdout o stderr, seguendo le linee guida di Twelve-Factor App che raccomandano di trattare i log come flussi di eventi piuttosto che gestire file di log. Vedere Creazione di applicazioni cloud-native: applicazioni a 12 fattori - Fattore 11 - Log.

La pipeline di registrazione della piattaforma acquisisce ed elabora automaticamente questo output, rendendolo disponibile per l'analisi e la risoluzione dei problemi. Le righe di log scritte nei file del file system effimero del contenitore non vengono ingerite, persistite o esposte attraverso l'interfaccia di log. Di conseguenza, i registri memorizzati sul file system effimero vengono persi quando l'istanza viene riavviata o terminata e non sono disponibili per il debugging operativo o l'analisi delle cause principali.

Devo aggiungere i timestamp alle mie linee di log?

I record di log generati dai carichi di lavoro degli utenti dovrebbero evitare di incorporare le proprie informazioni di timestamp, perché l'infrastruttura Code Engine acquisisce e standardizza automaticamente i timestamp. L'inclusione di timestamp a livello di applicazione può creare incoerenze tra i servizi, soprattutto quando i carichi di lavoro vengono eseguiti in ambienti distribuiti o containerizzati, dove gli orologi di sistema possono essere diversi o spostati. Affidarsi ai timestamp della piattaforma garantisce formati temporali uniformi, sequenze accurate e correlazioni affidabili con altri log generati dal sistema, semplificando la risoluzione dei problemi, l'auditing e l'osservabilità dell'intera implementazione.

Come si configurano i livelli di log rispetto alla severità di IBM Cloud Logs?

Il livello di log fornito in ciascun record di log viene mappato ai livelli di severità di IBM Cloud Logs come descritto in Mappatura dei livelli di severità del log ai livelli di severità di IBM Cloud Logs. Nelle sezioni seguenti vengono fornite ulteriori informazioni su come vengono analizzati i livelli di registro per i registri non strutturati e strutturati e sui valori dei livelli di registro supportati.

Cosa succede se i dati di log sono multilinea?

Per sfruttare le funzioni di ricerca e formattazione di IBM Cloud Logs, modificare la formattazione dei registri come segue.

• Se le linee di log si estendono su più righe, modificate il modo in cui formattate e producete i log in modo che siano su una sola riga. Utilizzare il formato JSONL (vedere Formati dei log ) per i log con IBM Cloud Logs.
• I vostri registri devono essere conformi ai limiti di IBM Cloud Logs.

Esempi

Di seguito sono riportati semplici esempi che scrivono una riga di log non strutturata (testo libero) sullo standard output.

Gli esempi sono pubblicati nel repository pubblico di esempi Code Engine all'indirizzo 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");
    }
}

Rilevamento del livello di log

Ogni record di registro viene analizzato alla ricerca di parole chiave per determinare la gravità. I valori di gravità, valutati in modo insensibile, sono critical, error, warn, info, debug e verbose.

Se una riga di registro inizia con una parola chiave di gravità nel formato LEVEL MESSAGE, Code Engine rimuove il livello rilevato dal messaggio di registro visualizzato, in modo che gli utenti possano concentrarsi sul contenuto principale, pur continuando a filtrare con precisione in base alla gravità nella vista IBM Cloud Logs. In questo caso, il valore di gravità estratto viene memorizzato nel campo del record di log level. Sono supportati i seguenti livelli di gravità senza distinzione tra maiuscole e minuscole: fatal, error, warn, info, debug, e trace. Ad esempio, in Node.js si potrebbe scrivere:

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

In IBM Cloud Logs, questa voce appare con la gravità Errore e il testo del messaggio "Timeout del servizio di pagamento durante la creazione della fattura "; è quindi possibile filtrare per Gravità = Errore per restringere i risultati. È inoltre possibile utilizzare le regole di parsing e di severità per adattare il modo in cui i livelli vengono estratti e abbinati al proprio ambiente.

Il rilevamento del livello di log funziona anche quando le linee di log seguono formati leggermente diversi, come LEVEL: MESSAGE o [LEVEL] MESSAGE. Tuttavia, in questi casi la parola chiave livello non viene rimossa dal messaggio di log, anche se la gravità è ancora classificata correttamente.

Inoltre, la logica di rilevamento può dedurre un livello di gravità quando una parola chiave supportata compare in qualsiasi punto del messaggio, non solo all'inizio. Ad esempio, la linea di log:

The payment workflow encountered an unexpected error during validation

Questa riga di registro è classificata come Errore perché nel testo del messaggio compare la parola errore.

Il rilevamento del livello di log non considera il flusso di ingresso (stdout o stderr) per il rilevamento del livello di log. Pertanto, i messaggi di log scritti sullo standard error (stderr) vengono valutati esclusivamente in base al testo del messaggio. Ad esempio, console.error("Some message") è classificato come Info, anche se viene scritto su stderr.

Per i carichi di lavoro funzionali, il livello di log non viene rimosso dal messaggio di log visualizzato, anche quando viene rilevato all'inizio della riga di log nel formato LEVEL MESSAGE.

Analisi e valutazione dei timestamp

L'aggiunta di timestamp alle linee di log delle applicazioni non è consigliata perché Code Engine assegna automaticamente un timestamp normalizzato quando i log vengono ingeriti. Se un timestamp è incluso all'inizio di una riga di log, il sistema tenta di analizzarlo. Se corrisponde a uno dei formati supportati, il timestamp viene rimosso dal messaggio di log visualizzato, in modo simile a come vengono gestiti i livelli di log. I formati di timestamp supportati includono:

• 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

Quando una riga di log contiene sia un timestamp che un livello di log all'inizio (ad esempio, TIMESTAMP LEVEL MESSAGE), la pipeline valuta entrambi i campi. Se entrambi corrispondono agli schemi supportati, vengono classificati in modo appropriato e rimossi dal messaggio di log renderizzato, lasciando solo il corpo del messaggio per facilitare la lettura e il filtraggio. Ad esempio, i seguenti formati vengono analizzati con successo:

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

Nei casi in cui un timestamp compare ma non corrisponde ai formati supportati, rimane parte della riga di log e viene trattato come testo normale, ma il resto del messaggio viene comunque elaborato normalmente.

Per i carichi di lavoro funzionali, i timestamp non vengono analizzati, valutati o rimossi dai messaggi di log. Qualsiasi timestamp incluso nei log delle funzioni rimane parte del messaggio visualizzato.

Supporto multilinea

Code Engine supporta voci di registro multilinea. Tuttavia, quando si emettono i log, è necessario assicurarsi che i caratteri di newline (\n) siano codificati correttamente (\\n), in modo che la pipeline di log possa elaborare e rendere correttamente i messaggi multilinea. Ad esempio, in Node.js, si può produrre una voce di log multilinea come questa:

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

Errori di registrazione

Se il carico di lavoro emette tracce di stack di errore a più righe, utilizzare il formato di log JSON strutturato invece dell'output non strutturato della console. I log strutturati conservano in modo affidabile i campi multilinea e assicurano che le tracce di stack siano raggruppate in un unico record di log, come descritto nella sezione Log strutturati.

Ad esempio, il seguente messaggio di log è classificato come Errore perché nel messaggio di log compare la parola chiave "error". Tuttavia, la traccia dello stack fornita dall'oggetto err viene resa in più righe di log.

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

Esempi

Di seguito sono riportati esempi minimi di log strutturato per ogni linguaggio e runtime che emettono un singolo JSON con il livello di log nel campo level e il messaggio di log nel campo message.

Gli esempi sono pubblicati nel repository pubblico di esempi Code Engine all'indirizzo 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 e Logback con 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");
  }
}

Rilevamento del livello di log

Ogni record di registro viene analizzato alla ricerca di parole chiave per determinare la gravità. I valori di gravità, valutati in modo insensibile, sono critical, error, warn, info, debug e verbose.

Quando si utilizzano log strutturati, Code Engine rileva automaticamente il livello di log quando viene fornito in uno dei seguenti campi: level, severity, o logLevel. Il valore di questi campi non fa distinzione tra maiuscole e minuscole, quindi voci come error, ERROR o Error corrispondono tutte alla stessa gravità. Sono supportati i seguenti livelli di gravità senza distinzione tra maiuscole e minuscole: critical, error, warn, info, debug, e verbose. Quando un campo supportato è presente e contiene uno di questi valori, il livello del registro viene estratto, normalizzato e utilizzato per il filtraggio e la categorizzazione nell'interfaccia utente dei registri. Ad esempio, le seguenti righe di log strutturate sono tutte correttamente interpretate con il livello Errore:

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

Indipendentemente dalla capitalizzazione o dal valore specifico del campo utilizzato, la piattaforma identifica correttamente il livello di log e lo applica per filtrare, raggruppare e analizzare i dati di log strutturati.

Valutazione del timestamp

Per i registri strutturati, i timestamp personalizzati non vengono analizzati o valutati. Qualsiasi campo timestamp fornito dall'utente viene trattato esclusivamente come dato di payload, mentre la piattaforma applica sempre il proprio timestamp di ingestione per l'ordinamento e il filtraggio.

Nell'esempio seguente, il valore "timestamp" viene conservato ma ignorato per i tempi di registrazione.

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

Aggiunta di ulteriori informazioni sul contesto

È possibile arricchire i log strutturati con campi personalizzati (ad esempio, requestId, userId, o metadati specifici del dominio). Di seguito sono riportati esempi minimi per ogni pila utilizzata in precedenza.

Mantenere i campi personalizzati concisi e stabili (ad esempio, ID, codici o piccoli enum) per massimizzare la filtrabilità e minimizzare la cardinalità nell'istanza di registrazione.

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 e Logback con logstash-logback-encoder )

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

Errori di registrazione

Per catturare sia il messaggio di errore che la sua traccia di stack in log strutturati, emettere un record JSON che includa i campi standard (level, message) più un campo stack (o simile).

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

I carichi di lavoro delle funzioni gestiscono registri a più righe, ma ogni carattere newline risulta in una voce di registro separata. Quando si registrano le tracce di stack con framework di registrazione strutturati, potrebbe essere necessario eseguire l'escape manuale dei caratteri di newline per assicurarsi che vengano resi correttamente come una singola voce di log.

È possibile applicare filtri ai dati di IBM Cloud Logs?

In base alle proprie esigenze, dalla pagina IBM Cloud Logs è possibile modificare e applicare il filtro per visualizzare i dati di log a un livello specifico o a un livello più granulare per una revisione specifica dell'applicazione, un'esecuzione di lavoro o un'esecuzione di build.

• Se è impostato app:"codeengine", vengono visualizzati solo i registri Code Engine.

• Se è impostato codeengine.project:'<project_name>', vengono visualizzati solo i registri di un progetto specifico.

• Se codeengine.component:'<your_component_name>' è impostato, vengono visualizzati solo i log del componente specificato (applicazione, lavoro o build). Se i componenti di Code Engine hanno lo stesso nome, il filtro include i log di questi componenti. Ad esempio,

  • Il filtro app:"codeengine" AND codeengine.component:"myapp" individua i registri a livello di applicazione myapp.
  • Il filtro app:"codeengine" AND codeengine.subcomponent:"myapp\-00002" individua i registri al livello di revisione dell'applicazione myapp-0002.
  • Il filtro app:"codeengine" AND codeengine.component:"myjob" consente di individuare i registri al livello di lavoro specifico di myjob.
  • Il filtro app:"codeengine" AND codeengine.subcomponent:"myjob\-jobrun\-t6m7l" consente di individuare i registri in base al livello di esecuzione del lavoro specifico myjob-jobrun-t6m7l.
  • Il filtro app:"codeengine" AND codeengine.component:"mybuild" individua i registri in base al livello di compilazione specifico di mybuild.
  • Il filtro app:"codeengine" AND codeengine.subcomponent:"mybuild\-run\-121212" individua i registri al livello di esecuzione specifico della build mybuild-run-121212.

Per ulteriori informazioni sulla configurazione e l'avvio della registrazione nella console, vedere Visualizzazione dei registri di app, lavori o funzioni dalla console.