编写和查看应用程序、工作和功能的日志

将日志写入标准输出和错误

在 Code Engine 中，工作负载产生的日志记录只有在写入 stdout 或 stderr 时才会被收集，这符合 Twelve-Factor App 指南，该指南建议将日志视为事件流，而不是管理日志文件。 请参阅 创建云原生应用程序：12 要素应用程序 - 要素 11 - 日志。

该平台的日志管道可自动捕获和处理这些输出，以便进行分析和故障排除。 写入容器短暂文件系统中文件的日志行不会被摄取、持久化或通过日志接口公开。 因此，在重启或终止实例时，存储在短暂文件系统上的任何日志都会丢失，无法用于操作调试或根本原因分析。

我是否应该在日志行中添加时间戳？

用户工作负载生成的日志记录应避免嵌入自己的时间戳信息，因为 Code Engine 基础架构会自动捕获时间戳并将其标准化。 包含应用级时间戳会造成服务间的不一致，尤其是当工作负载在分布式或容器化环境中运行时，系统时钟可能会漂移或不同。 依靠平台的时间戳可确保统一的时间格式、准确的排序以及与其他系统生成的日志的可靠关联，从而简化整个部署的故障排除、审计和可观察性。

我的日志级别如何映射到 IBM Cloud Logs 严重性？

如 将日志严重性映射到 IBM Cloud Logs 严重性 所述，每条日志记录中提供的日志级别都会映射到 IBM Cloud Logs severities 中。 在以下各节中，您将进一步了解如何解析非结构化日志和结构化日志的日志级别，以及支持哪些日志级别值。

如果我的日志数据是多行数据怎么办？

要利用 IBM Cloud Logs 的搜索和格式化功能，请按以下步骤更改日志格式。

• 如果您的日志行跨越多行，请更改格式和输出日志的方式，使它们成为一行。 使用 JSONL 格式（请参阅日志 格式 ）记录日志，IBM Cloud Logs。
• 您的日志必须符合 IBM Cloud Logs 的限制。

示例

以下是将非结构化日志行（自由格式文本）写入标准输出的简单示例。

这些示例发布在 Code Engine 公共示例库中，网址为 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");
    }
}

日志级别检测

对每条日志记录进行关键字扫描，以确定严重程度。 严重程度值是按不敏感的情况进行评估的，它们是 critical, error, warn, info, debug，和 verbose。

如果日志行以 LEVEL MESSAGE 格式的严重性关键字开头，Code Engine 就会从显示的日志信息中移除检测到的级别，这样用户就可以专注于核心内容，同时仍可在 IBM Cloud Logs 视图中按严重性进行精确过滤。 在这种情况下，提取的严重性值将存储在日志记录字段 level 中。 支持以下不区分大小写的严重性级别：fatal, error, warn, info, debug，和 trace。 例如，您可以在 Node.js 中写道：

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

在 IBM Cloud Logs 中，该条目显示的严重性为错误，信息文本为“创建发票时支付服务超时”；您可以根据严重性 = 错误进行筛选，缩小结果范围。 您还可以使用解析和严重性规则来调整提取和匹配级别的方式，以适应您的环境。

当日志行的格式略有不同时，日志级别检测也能发挥作用，例如 LEVEL: MESSAGE 或 [LEVEL] MESSAGE。 不过，在这些情况下，即使严重性仍被正确分类，也不会从日志信息中删除级别关键字。

此外，当任何受支持的关键字出现在信息的任何位置 （而不仅仅是开头）时，检测逻辑都能推断出严重程度。 例如，日志行：

The payment workflow encountered an unexpected error during validation

该日志行被归类为“错误”，因为消息文本中出现了“错误”一词。

日志级别检测不考虑用于日志级别检测的输入流（stdout 或 stderr ）。 因此，写入标准错误 (stderr) 的日志信息仅根据信息文本进行评估。 例如，console.error("Some message") 被归类为 Info，尽管它被写入了 stderr。

对于功能工作负载，即使在日志行开头检测到日志级别，也不会从显示的日志信息中删除，格式为 LEVEL MESSAGE。

时间戳解析和评估

不建议在应用程序日志行中添加时间戳，因为 Code Engine 会在接收日志时自动分配规范化时间戳。 如果日志行开头包含时间戳，系统会尝试对其进行解析。 如果时间戳与支持的格式之一匹配，则会从显示的日志信息中移除时间戳，这与日志级别的处理方式类似。 支持的时间戳格式包括

• 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

当日志行开头同时包含时间戳和日志级别（例如 TIMESTAMP LEVEL MESSAGE ）时，管道会对这两个字段进行评估。 如果两者都符合支持的模式，则会分别进行适当分类，并从渲染的日志信息中删除，只留下信息正文，以便于阅读和过滤。 例如，以下格式已成功解析：

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

如果时间戳出现但不符合支持的格式，它仍是日志行的一部分，并被视为常规文本，但信息的其他部分仍会正常处理。

对于函数工作负载，不会解析、评估或删除日志信息中的时间戳。 功能日志中包含的任何时间戳都会保留在显示的信息中。

多线支持

Code Engine 支持多行日志条目。 不过，在发布日志时，必须确保换行符 (\n) 被正确编码 (\\n)，这样日志管道才能正确处理和呈现多行信息。 例如，在 Node.js 中，可以生成类似的多行日志条目：

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

记录错误

如果工作负载会发出多行错误堆栈跟踪，请使用结构化的 JSON 日志格式，而不是非结构化的控制台输出。 结构化日志能可靠地保留多行字段，并确保将堆栈跟踪归类到单个日志记录中，这将在 结构化日志 一节中介绍。

例如，以下日志信息被归类为错误，因为日志信息中出现了关键字 "error"。 但是，err 对象提供的堆栈跟踪会显示在多行日志中。

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

示例

以下是每种语言和运行时的 最小结构化日志示例，这些语言和运行时会发出一个 JSON，其中 level 字段包含日志 夷为平地，message 字段包含日志 信息。

这些示例发布在 Code Engine 公共示例库中，网址为 https://github.com/IBM/CodeEngine/blob/main/logging/README.md。

Node.js （ 温斯顿）

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 （ 罗古鲁）

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 ( 泔水 )

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

日志级别检测

对每条日志记录进行关键字扫描，以确定严重程度。 严重程度值是按不敏感的情况进行评估的，它们是 critical, error, warn, info, debug，和 verbose。

使用结构化日志时，Code Engine 会自动检测以下字段中提供的日志级别：level, severity，或 logLevel。 这些字段中的值不区分大小写，这意味着 error, ERROR 或 Error 等条目都映射到相同的严重性。 支持以下不区分大小写的严重性级别：critical, error, warn, info, debug，和 verbose。 如果支持的字段中包含这些值之一，则会提取日志级别，对其进行规范化处理，并在日志用户界面中用于过滤和分类。 例如，以下结构化日志行均可正确解释为错误级别：

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

无论使用的是大写还是特定字段值，平台都能正确识别日志级别，并将其应用于结构化日志数据的过滤、分组和分析。

时间戳评估

对于结构化日志，不会解析或评估自定义时间戳。 您提供的任何时间戳字段都会被纯粹视为有效载荷数据，而平台始终会应用自己的摄取时间戳来进行排序和筛选。

在下面的示例中，"timestamp"值被保留，但在日志计时时被忽略。

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

添加额外的上下文信息

您可以使用自定义字段（例如 requestId、userId 或特定域元数据）来丰富结构化日志。 下面是前面使用的每个堆栈的最小示例。

保持自定义字段简洁、稳定（例如，ID、代码或小型枚举），以便在日志实例中最大限度地提高可过滤性并减少卡片数量。

Node.js （ 温斯顿）

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

Python （ 罗古鲁）

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

Golang ( 泔水 )

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

Java ( SLF4J 和 Logback 与 logstash-logback-encoder )

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

记录错误

要在结构化日志中捕获 两个 错误信息及其 堆栈跟踪，可生成一条 JSON 记录，其中包括标准字段 (level, message) 和 stack （或类似字段）。

Node.js （ 温斯顿）

// 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 （ 罗古鲁）

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

Golang ( 泔水 )

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

函数工作负载可处理多行日志，但每个换行符都会产生一个单独的日志条目。 使用结构化日志框架记录堆栈跟踪时，可能需要手动转义换行符，以确保它们能正确呈现为单个日志条目。

能否在 IBM Cloud Logs 数据上应用筛选器？

您可以根据自己的需要，在 IBM Cloud Logs 页面修改筛选器并确定其范围，以显示特定级别的日志数据，或更细粒度地显示特定应用程序版本、作业运行或构建运行的日志数据。

• 如果设置为 app:"codeengine"，则只显示 Code Engine 日志。

• 如果设置了 codeengine.project:'<project_name>'，则只显示特定项目的日志。

• 如果设置了 codeengine.component:'<your_component_name>'，则只显示指定组件（应用程序、作业或构建）的日志。 如果 Code Engine 组件名称相同，则过滤器会包含这些组件的日志。 例如，

  • 过滤器 app:"codeengine" AND codeengine.component:"myapp" 将日志范围扩展到 myapp 应用程序级别。
  • 过滤器 app:"codeengine" AND codeengine.subcomponent:"myapp\-00002" 将日志范围扩展到 myapp-0002 应用程序修订级别。
  • 过滤器 app:"codeengine" AND codeengine.component:"myjob" 将日志范围扩展到特定的 myjob 作业级别。
  • 过滤器 app:"codeengine" AND codeengine.subcomponent:"myjob\-jobrun\-t6m7l" 将日志范围限定为特定的 myjob-jobrun-t6m7l 作业运行级别。
  • 过滤器 app:"codeengine" AND codeengine.component:"mybuild" 将日志范围限定为特定的 mybuild 构建级别。
  • 过滤器 app:"codeengine" AND codeengine.subcomponent:"mybuild\-run\-121212" 将日志范围限定为特定的 mybuild-run-121212 构建运行级别。

有关在控制台中配置和启动日志记录的更多信息，请参阅 从控制台查看应用程序、任务或功能日志。