Gravação de logs na saída padrão e no erro

Em Code Engine, os registros de log emitidos pela sua carga de trabalho são coletados somente quando são gravados em stdout ou stderr, seguindo as diretrizes do aplicativo Twelve-Factor, que recomendam tratar os logs como fluxos de eventos em vez de gerenciar arquivos de log. Consulte Criação de aplicativos nativos da nuvem: aplicativos com 12 fatores - Fator 11 - Registros.

O pipeline de registro da plataforma captura e processa automaticamente essa saída, tornando-a disponível para análise e solução de problemas. As linhas de registro gravadas em arquivos no sistema de arquivos efêmeros do contêiner não são ingeridas, mantidas ou expostas por meio da interface de registro. Como resultado, todos os registros armazenados no sistema de arquivos efêmeros são perdidos quando a instância é reiniciada ou encerrada e não estão disponíveis para depuração operacional ou análise da causa raiz.

Devo adicionar registros de data e hora às minhas linhas de registro?

Os registros de log gerados pelas cargas de trabalho do usuário devem evitar a incorporação de suas próprias informações de carimbo de data/hora, pois a infraestrutura do Code Engine captura e padroniza automaticamente os carimbos de data/hora. A inclusão de carimbos de data/hora no nível do aplicativo pode criar inconsistências entre os serviços, especialmente quando as cargas de trabalho são executadas em ambientes distribuídos ou em contêineres, nos quais os relógios do sistema podem variar ou ser diferentes. Confiar nos carimbos de data e hora da plataforma garante formatos de hora uniformes, sequenciamento preciso e correlação confiável com outros logs gerados pelo sistema, o que simplifica a solução de problemas, a auditoria e a observabilidade em toda a implementação.

Como meus níveis de registro são mapeados para a gravidade do IBM Cloud Logs?

O nível de log fornecido em cada registro de log é mapeado para as severidades do site IBM Cloud Logs, conforme descrito em Mapeamento das severidades de log para as severidades do site IBM Cloud Logs. Nas seções a seguir, você saberá mais sobre como os níveis de log são analisados para logs não estruturados e estruturados e quais valores de nível de log são suportados.

E se meus dados de registro tiverem várias linhas?

Para aproveitar os recursos de pesquisa e formatação do IBM Cloud Logs, altere a formatação do registro da seguinte forma.

• Se as linhas de registro abrangerem várias linhas, altere a forma de formatação e saída dos registros para que fiquem em uma única linha. Use o formato JSONL (consulte Formatos de registro ) para seus registros com IBM Cloud Logs.
• Seus registros devem estar em conformidade com os limites para IBM Cloud Logs.

Exemplos

Abaixo estão exemplos simples que gravam uma linha de registro não estruturada (texto de forma livre) na saída padrão.

Os exemplos estão publicados no repositório público de amostras Code Engine em 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");
    }
}

Detecção de nível de registro

Cada registro de log é examinado em busca de palavras-chave para determinar a gravidade. Os valores de gravidade, que são avaliados de forma insensível ao caso, são critical, error, warn, info, debug e verbose.

Se uma linha de log começar com uma palavra-chave de gravidade no formato LEVEL MESSAGE, Code Engine removerá o nível detectado da mensagem de log exibida para que os usuários possam se concentrar no conteúdo principal e ainda filtrar com precisão por gravidade na visualização IBM Cloud Logs. Nesse caso, o valor de gravidade extraído é armazenado no campo de registro de log level. Há suporte para os seguintes níveis de gravidade sem distinção entre maiúsculas e minúsculas: fatal, error, warn, info, debug, e trace. Por exemplo, em Node.js você pode escrever:

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

Em IBM Cloud Logs, essa entrada aparece com a gravidade Erro e o texto da mensagem "Tempo limite do serviço de pagamento durante a criação da fatura"; você pode então filtrar por Gravidade = Erro para restringir os resultados. Você também pode usar regras de análise e gravidade para personalizar a forma como os níveis são extraídos e combinados em seu ambiente.

A detecção do nível de registro também funciona quando as linhas de registro seguem formatos ligeiramente diferentes, como LEVEL: MESSAGE ou [LEVEL] MESSAGE. No entanto, nesses casos, a palavra-chave level não é removida da mensagem de registro, mesmo que a gravidade ainda esteja classificada corretamente.

Além disso, a lógica de detecção pode inferir um nível de gravidade quando qualquer palavra-chave compatível aparece em qualquer lugar da mensagem, não apenas no início. Por exemplo, a linha de registro:

The payment workflow encountered an unexpected error during validation

Essa linha de registro é classificada como Erro porque a palavra erro aparece no texto da mensagem.

A detecção do nível de registro não considera o fluxo de entrada (stdout ou stderr) para a detecção do nível de registro. Portanto, as mensagens de registro gravadas no erro padrão (stderr) são avaliadas exclusivamente no texto da mensagem. Por exemplo, console.error("Some message") é classificado como Info, embora seja gravado em stderr.

Para cargas de trabalho de função, o nível de registro não é removido da mensagem de registro exibida, mesmo quando é detectado no início da linha de registro no formato LEVEL MESSAGE.

Análise e avaliação de carimbo de data/hora

Não é recomendável adicionar carimbos de data/hora às linhas de registro de aplicativos porque o site Code Engine atribui automaticamente um carimbo de data/hora normalizado quando os registros são ingeridos. Se um registro de data e hora for incluído no início de uma linha de registro, o sistema tentará analisá-lo. Se corresponder a um dos formatos suportados, o carimbo de data/hora será removido da mensagem de registro exibida, de forma semelhante à maneira como os níveis de registro são tratados. Os formatos de registro de data e hora compatíveis incluem:

• 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 uma linha de registro contém um carimbo de data/hora e um nível de registro no início (por exemplo, TIMESTAMP LEVEL MESSAGE), o pipeline avalia os dois campos. Se ambos corresponderem aos padrões suportados, cada um deles será classificado adequadamente e removido da mensagem de registro renderizada, deixando apenas o corpo da mensagem para facilitar a leitura e a filtragem. Por exemplo, os seguintes formatos são analisados com sucesso:

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

Nos casos em que um carimbo de data/hora aparece, mas não corresponde aos formatos compatíveis, ele permanece como parte da linha de registro e é tratado como texto normal, mas o restante da mensagem ainda é processado normalmente.

Para cargas de trabalho de função, os carimbos de data/hora não são analisados, avaliados ou removidos das mensagens de registro. Qualquer registro de data e hora incluído nos logs de função permanece como parte da mensagem exibida.

Suporte multilinha

Code Engine suporta entradas de registro com várias linhas. No entanto, ao emitir registros, você deve garantir que os caracteres de nova linha (\n) sejam codificados corretamente (\\n) para que o pipeline de registro possa processar e renderizar corretamente as mensagens de várias linhas. Por exemplo, em Node.js, é possível produzir uma entrada de registro de várias linhas como esta:

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

Registro de erros

Se a sua carga de trabalho emitir rastreamentos de pilha de erros de várias linhas, use o formato de log JSON estruturado em vez da saída não estruturada do console. Os logs estruturados preservam os campos de várias linhas de forma confiável e garantem que os rastreamentos de pilha sejam agrupados em um único registro de log, o que é abordado na seção Logs estruturados.

Por exemplo, a mensagem de registro a seguir é classificada como Erro porque a palavra-chave "error" aparece na mensagem de registro. No entanto, o rastreamento de pilha fornecido pelo objeto err é renderizado em várias linhas de registro.

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

Exemplos

A seguir, exemplos mínimos de registro estruturado para cada linguagem e tempo de execução que emitem um único JSON com o nível de registro no campo level e a mensagem de registro no campo message.

Os exemplos estão publicados no repositório público de amostras Code Engine em 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 com 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");
  }
}

Detecção de nível de registro

Cada registro de log é examinado em busca de palavras-chave para determinar a gravidade. Os valores de gravidade, que são avaliados de forma insensível ao caso, são critical, error, warn, info, debug e verbose.

Quando você usa logs estruturados, o Code Engine detecta automaticamente o nível de log quando ele é fornecido em um dos campos a seguir: level, severity, ou logLevel. O valor nesses campos não diferencia maiúsculas de minúsculas, o que significa que entradas como error, ERROR ou Error são mapeadas para a mesma gravidade. Há suporte para os seguintes níveis de gravidade sem distinção entre maiúsculas e minúsculas: critical, error, warn, info, debug, e verbose. Quando um campo compatível está presente e contém um desses valores, o nível de registro é extraído, normalizado e usado para filtragem e categorização na interface do usuário de registros. Por exemplo, as seguintes linhas de registro estruturadas são todas interpretadas corretamente com o nível Error:

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

Independentemente da capitalização ou do valor de campo específico usado, a plataforma identifica corretamente o nível de registro e o aplica para filtragem, agrupamento e análise em seus dados de registro estruturados.

Avaliação de carimbo de data/hora

Para registros estruturados, os carimbos de data e hora personalizados não são analisados ou avaliados. Qualquer campo de registro de data e hora fornecido por você é tratado exclusivamente como dados de carga útil, enquanto a plataforma sempre aplica seu próprio registro de data e hora de ingestão para ordenação e filtragem.

No exemplo abaixo, o valor "timestamp" é preservado, mas ignorado para o tempo de registro.

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

Adição de informações adicionais de contexto

Você pode enriquecer os registros estruturados com campos personalizados (por exemplo, requestId, userId, ou metadados específicos do domínio). A seguir, exemplos mínimos de cada pilha usada anteriormente.

Mantenha os campos personalizados concisos e estáveis (por exemplo, IDs, códigos ou pequenos enums) para maximizar a capacidade de filtragem e minimizar a cardinalidade em sua instância 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 e Logback com logstash-logback-encoder )

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

Registro de erros

Para capturar ambos a mensagem de erro e sua rastreamento de pilha em logs estruturados, emita um registro JSON que inclua seus campos padrão (level, message) mais um campo stack (ou 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 e Logback com 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");
}

As cargas de trabalho de funções lidam com registros de várias linhas, mas cada caractere de nova linha resulta em uma entrada de registro separada. Ao registrar traços de pilha com estruturas de registro estruturado, talvez seja necessário escapar manualmente dos caracteres de nova linha para garantir que eles sejam renderizados corretamente como uma única entrada de registro.

Posso aplicar filtros nos dados do site IBM Cloud Logs?

Você pode modificar e definir o escopo do filtro para exibir dados de log em um nível específico ou em um nível mais granular para uma revisão específica do aplicativo, execução de trabalho ou execução de compilação na página IBM Cloud Logs, com base em suas necessidades.

• Se app:"codeengine" estiver definido, somente os registros de Code Engine serão exibidos.

• Se codeengine.project:'<project_name>' for definido, somente os registros de um projeto específico serão exibidos.

• Se codeengine.component:'<your_component_name>' for definido, somente os registros do componente especificado (aplicativo, trabalho ou compilação) serão exibidos. Se os componentes do site Code Engine tiverem o mesmo nome, o filtro incluirá os logs desses componentes. Por exemplo,

  • O filtro app:"codeengine" AND codeengine.component:"myapp" limita os logs ao nível do aplicativo myapp.
  • O filtro app:"codeengine" AND codeengine.subcomponent:"myapp\-00002" limita os logs ao nível de revisão do aplicativo myapp-0002.
  • O filtro app:"codeengine" AND codeengine.component:"myjob" restringe os logs ao nível específico do trabalho myjob.
  • O filtro app:"codeengine" AND codeengine.subcomponent:"myjob\-jobrun\-t6m7l" restringe os logs ao nível de execução do trabalho myjob-jobrun-t6m7l específico.
  • O filtro app:"codeengine" AND codeengine.component:"mybuild" restringe os logs ao nível de compilação específico do mybuild.
  • O filtro app:"codeengine" AND codeengine.subcomponent:"mybuild\-run\-121212" restringe os logs ao nível de execução de compilação mybuild-run-121212 específico.

Para obter mais informações sobre como configurar e iniciar o registro em log no console, consulte Visualização de logs de aplicativos, trabalhos ou funções no console.