Escritura y visualización de registros de aplicaciones, trabajos y funciones

Escritura de registros en salida estándar y error

En Code Engine, los registros de logs emitidos por su carga de trabajo se recopilan sólo cuando se escriben en stdout o stderr, siguiendo las directrices de la App de Doce Factores que recomiendan tratar los logs como flujos de eventos en lugar de gestionar archivos de logs. Véase Creación de aplicaciones nativas de la nube: aplicaciones de 12 factores - Factor 11 - Registros.

El canal de registro de la plataforma captura y procesa automáticamente este resultado, poniéndolo a disposición para el análisis y la resolución de problemas. Las líneas de registro escritas en archivos del sistema de archivos efímero del contenedor no se ingieren, persisten ni se exponen a través de la interfaz de registro. Como resultado, cualquier registro almacenado en el sistema de archivos efímero se pierde cuando la instancia se reinicia o finaliza y no está disponible para la depuración operativa o el análisis de la causa raíz.

¿Debo añadir marcas de tiempo a mis líneas de registro?

Los registros de logs generados por las cargas de trabajo de los usuarios deben evitar incrustar su propia información de marca de tiempo porque la infraestructura Code Engine captura y estandariza automáticamente las marcas de tiempo. Incluir marcas de tiempo a nivel de aplicación puede crear incoherencias entre los servicios, especialmente cuando las cargas de trabajo se ejecutan en entornos distribuidos o en contenedores en los que los relojes del sistema pueden variar o diferir. Confiar en las marcas de tiempo de la plataforma garantiza formatos de tiempo uniformes, secuenciación precisa y correlación fiable con otros registros generados por el sistema, lo que simplifica la solución de problemas, la auditoría y la observabilidad en toda la implantación.

¿Cómo se corresponden mis niveles de registro con la gravedad de IBM Cloud Logs?

El nivel de registro proporcionado en cada registro se asigna a las severidades de IBM Cloud Logs como se describe en Asignación de severidades de registro a severidades de IBM Cloud Logs. En las siguientes secciones, aprenderá más sobre cómo se analizan los niveles de registro para registros estructurados y no estructurados y qué valores de nivel de registro son compatibles.

¿Qué pasa si mis datos de registro son multilínea?

Para aprovechar las funciones de búsqueda y formato de IBM Cloud Logs, cambie el formato de su registro de la siguiente manera.

• Si sus líneas de registro abarcan varias líneas, cambie el formato y la salida de sus registros para que estén en una sola línea. Utilice el formato JSONL (véase Formatos de registro ) para sus registros con IBM Cloud Logs.
• Sus troncos deben ajustarse a los límites de IBM Cloud Logs.

Ejemplos

A continuación se muestran ejemplos sencillos que escriben una línea de registro no estructurada (texto de forma libre) en la salida estándar.

Los ejemplos están publicados en el repositorio público de muestras Code Engine en 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");
    }
}

Detección del nivel de registro

Cada registro se analiza en busca de palabras clave para determinar la gravedad. Los valores de gravedad, que se evalúan caso por caso, son critical, error, warn, info, debug, y verbose.

Si una línea de registro comienza con una palabra clave de gravedad en el formato LEVEL MESSAGE, Code Engine elimina el nivel detectado del mensaje de registro mostrado para que los usuarios puedan centrarse en el contenido principal sin dejar de filtrar con precisión por gravedad en la vista IBM Cloud Logs. En este caso, el valor de gravedad extraído se almacena en el campo de registro level. Se admiten los siguientes niveles de gravedad sin distinción entre mayúsculas y minúsculas: fatal, error, warn, info, debug, y trace. Por ejemplo, en Node.js podría escribir:

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

En IBM Cloud Logs, esta entrada aparece con la gravedad Error y el texto del mensaje "Tiempo de espera del servicio de pago al crear la factura "; a continuación, puede filtrar por Gravedad = Error para limitar los resultados. También puede utilizar reglas de análisis sintáctico y de gravedad para adaptar la extracción y la correspondencia de niveles a su entorno.

La detección del nivel de registro también funciona cuando las líneas de registro siguen formatos ligeramente diferentes, como LEVEL: MESSAGE o [LEVEL] MESSAGE. Sin embargo, en estos casos la palabra clave level no se elimina del mensaje de registro, aunque la gravedad siga estando correctamente clasificada.

Además, la lógica de detección puede inferir un nivel de gravedad cuando cualquier palabra clave admitida aparece en cualquier parte del mensaje, no sólo al principio. Por ejemplo, la línea de registro:

The payment workflow encountered an unexpected error during validation

Esta línea de registro se clasifica como Error porque la palabra error aparece en el texto del mensaje.

La detección del nivel de registro no tiene en cuenta el flujo de entrada (stdout o stderr) para la detección del nivel de registro. Por lo tanto, los mensajes de registro escritos en el error estándar (stderr) se evalúan únicamente en función del texto del mensaje. Por ejemplo, console.error("Some message") se clasifica como Info, aunque se escribe en stderr.

Para las cargas de trabajo de función, el nivel de registro no se elimina del mensaje de registro mostrado, incluso cuando se detecta al principio de la línea de registro en el formato LEVEL MESSAGE.

Análisis y evaluación de marcas de tiempo

No se recomienda añadir marcas de tiempo a las líneas de registro de la aplicación porque Code Engine asigna automáticamente una marca de tiempo normalizada cuando se ingieren los registros. Si se incluye una marca de tiempo al principio de una línea de registro, el sistema intenta analizarla. Si coincide con uno de los formatos admitidos, la marca de tiempo se elimina del mensaje de registro mostrado, de forma similar a cómo se gestionan los niveles de registro. Los formatos de fecha y hora admitidos son:

• 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

Cuando una línea de registro contiene tanto una marca de tiempo como un nivel de registro al principio (por ejemplo, TIMESTAMP LEVEL MESSAGE), el canal evalúa ambos campos. Si ambos coinciden con los patrones admitidos, cada uno de ellos se clasifica adecuadamente y se elimina del mensaje de registro renderizado, dejando sólo el cuerpo del mensaje para facilitar su lectura y filtrado. Por ejemplo, los siguientes formatos se analizan correctamente:

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

En los casos en que aparece una marca de tiempo pero no coincide con los formatos admitidos, sigue formando parte de la línea de registro y se trata como texto normal, pero el resto del mensaje se sigue procesando con normalidad.

Para las cargas de trabajo de funciones, las marcas de tiempo no se analizan, evalúan ni eliminan de los mensajes de registro. Cualquier marca de tiempo incluida en los registros de funciones sigue formando parte del mensaje mostrado.

Asistencia multilínea

Code Engine admite entradas de registro de varias líneas. Sin embargo, cuando emita registros, debe asegurarse de que los caracteres de nueva línea (\n) estén codificados correctamente (\\n) para que el canal de registro pueda procesar y renderizar correctamente los mensajes multilínea. Por ejemplo, en Node.js, puede producir una entrada de registro de varias líneas como ésta:

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

Registro de errores

Si su carga de trabajo emite trazas de pila de error de varias líneas, utilice el formato de registro JSON estructurado en lugar de la salida de consola no estructurada. Los registros estructurados conservan los campos multilínea de forma fiable y garantizan que las trazas de pila se agrupen en un único registro de registro, lo que se trata en la sección Registros estructurados.

Por ejemplo, el siguiente mensaje de registro se clasifica como Error porque la palabra clave "error" aparece en el mensaje de registro. Sin embargo, el seguimiento de pila que proporciona el objeto err se muestra en varias líneas de registro.

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

Ejemplos

Los siguientes son ejemplos mínimos de registro estructurado para cada lenguaje y tiempo de ejecución que emiten un único JSON con el nivel de registro en el campo level y el mensaje de registro en el campo message.

Los ejemplos están publicados en el repositorio público de muestras Code Engine en 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 y 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");
  }
}

Detección del nivel de registro

Cada registro se analiza en busca de palabras clave para determinar la gravedad. Los valores de gravedad, que se evalúan caso por caso, son critical, error, warn, info, debug, y verbose.

Cuando se utilizan registros estructurados, Code Engine detecta automáticamente el nivel de registro cuando se proporciona en uno de los siguientes campos: level, severity, o logLevel. El valor de estos campos no distingue entre mayúsculas y minúsculas, lo que significa que entradas como error, ERROR o Error corresponden a la misma gravedad. Se admiten los siguientes niveles de gravedad sin distinción entre mayúsculas y minúsculas: critical, error, warn, info, debug, y verbose. Cuando un campo compatible está presente y contiene uno de estos valores, se extrae el nivel de registro, se normaliza y se utiliza para el filtrado y la categorización dentro de la interfaz de usuario de registros. Por ejemplo, las siguientes líneas de registro estructuradas se interpretan correctamente con el nivel Error:

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

Independientemente de la capitalización o del valor de campo específico utilizado, la plataforma identifica correctamente el nivel de registro y lo aplica para filtrar, agrupar y analizar sus datos de registro estructurados.

Evaluación del sello de tiempo

En el caso de los registros estructurados, las marcas de tiempo personalizadas no se analizan ni evalúan. Cualquier campo de marca de tiempo que proporcione se trata puramente como datos de carga útil, mientras que la plataforma siempre aplica su propia marca de tiempo de ingestión para ordenar y filtrar.

En el siguiente ejemplo, el valor "timestamp" se conserva pero se ignora para la temporización del registro.

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

Añadir información contextual adicional

Puede enriquecer los registros estructurados con campos personalizados (por ejemplo, requestId, userId, o metadatos específicos del dominio). A continuación se presentan ejemplos mínimos para cada pila utilizada anteriormente.

Mantenga los campos personalizados concisos y estables (por ejemplo, IDs, códigos o pequeños enums) para maximizar la filtrabilidad y minimizar la cardinalidad en su instancia de registro.

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

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

Registro de errores

Para capturar tanto el mensaje de error como su seguimiento de pila en registros estructurados, emita un registro JSON que incluya sus campos estándar (level, message) más un campo stack (o similar).

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

Las cargas de trabajo funcionales manejan registros multilínea, pero cada carácter de nueva línea da lugar a una entrada de registro independiente. Cuando se registran trazas de pila con marcos de registro estructurados, es posible que tenga que escapar manualmente caracteres de nueva línea para asegurarse de que se representan correctamente como una sola entrada de registro.

¿Puedo aplicar filtros a los datos de IBM Cloud Logs?

Puede modificar y ampliar el filtro para mostrar los datos de registro a un nivel específico o a un nivel más granular para una revisión de aplicación específica, una ejecución de trabajo o una ejecución de compilación desde la página IBM Cloud Logs, en función de sus necesidades.

• Si se define app:"codeengine", sólo se mostrarán los registros de Code Engine.

• Si se define codeengine.project:'<project_name>', sólo se mostrarán los registros de un proyecto específico.

• Si se define codeengine.component:'<your_component_name>', sólo se mostrarán los registros del componente especificado (aplicación, trabajo o compilación). Si sus componentes de Code Engine comparten el mismo nombre, el filtro incluye los registros de estos componentes. Por ejemplo:

  • El filtro app:"codeengine" AND codeengine.component:"myapp" limita los registros al nivel de aplicación myapp.
  • El filtro app:"codeengine" AND codeengine.subcomponent:"myapp\-00002" limita los registros al nivel de revisión de la aplicación myapp-0002.
  • El filtro app:"codeengine" AND codeengine.component:"myjob" limita los registros al nivel de trabajo específico de myjob.
  • El filtro app:"codeengine" AND codeengine.subcomponent:"myjob\-jobrun\-t6m7l" limita los registros al nivel específico de ejecución del trabajo myjob-jobrun-t6m7l.
  • El filtro app:"codeengine" AND codeengine.component:"mybuild" limita los registros al nivel de compilación específico de mybuild.
  • El filtro app:"codeengine" AND codeengine.subcomponent:"mybuild\-run\-121212" limita los registros al nivel de ejecución específico de la compilación mybuild-run-121212.

Para obtener más información sobre la configuración y el inicio del registro en la consola, consulte Visualización de registros de aplicaciones, trabajos o funciones desde la consola.