為應用程式、工作和功能撰寫和檢視日誌

將日誌寫入標準輸出和錯誤

在 Code Engine 中，工作負載產生的日誌記錄只有在寫入 stdout 或 stderr 時才會被收集，並遵循 Twelve-Factor App 指南，該指南建議將日誌視為事件流，而不是管理日誌檔案。 請參閱 建立雲端原生應用程式：12 因子應用程式 - 因子 11 - 日誌。

平台的日誌管道會自動擷取和處理這些輸出，使其可用於分析和故障排除。 寫入容器暫存檔案系統中檔案的日誌行不會被擷取、持久化或透過日誌介面揭露。 因此，當重新啟動或終止實體時，儲存在短暫檔案系統上的任何日誌都會遺失，無法用於作業除錯或根本原因分析。

我是否應該在日誌行中加入時間戳記？

使用者工作負載產生的日誌記錄應避免嵌入自己的時間戳資訊，因為 Code Engine 基礎結構會自動擷取時間戳並將其標準化。 包含應用程式層級的時間戳記可能會造成服務間的不一致，尤其是工作負載在分散式或容器化環境中執行時，系統時鐘可能會偏移或不同。 依賴平台的時間戳記，可確保統一的時間格式、精確的順序，以及與其他系統產生的日誌之間的可靠關聯，從而簡化整個部署的故障排除、稽核和可觀察性。

我的日誌層級如何對應 IBM Cloud Logs 嚴重性？

每個日誌記錄中提供的日誌層級會對應到 IBM Cloud Logs 嚴重性，如將日誌 嚴重性對應到 IBM Cloud Logs 嚴重性 所述。 在接下來的章節中，您將進一步瞭解如何解析非結構化和結構化日誌的日誌層級，以及支援哪些日誌層級值。

如果我的日誌資料是多行資料，該怎麼辦？

若要利用 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 中，此項目顯示為嚴重程度 Error 和訊息文字 "Payment service timeout while creating invoice "；然後您可以依嚴重程度 = Error 篩選，以縮窄結果範圍。 您也可以使用解析和嚴重性規則，為您的環境量身訂做萃取和匹配層級的方式。

當日誌行遵循略有不同的格式時，日誌層級偵測也能運作，例如 LEVEL: MESSAGE 或 [LEVEL] MESSAGE。 然而，在這些情況下，level 關鍵字不會從記錄訊息中移除，儘管嚴重性仍被正確分類。

此外，偵測邏輯可以在任何支援的關鍵字出現時推斷嚴重等級 訊息中的任何位置，而不只是在開頭。 例如，日誌行：

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，因為關鍵字 "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 ( 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 和 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。 當支援的欄位存在並包含這些值之一時，會擷取記錄層級，將其規範化，並用於記錄使用者介面中的篩選和分類。 例如，以下結構化的日誌行都是以等級 Error 來正確詮釋的：

{ "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, 或特定網域的 metadata) 來豐富結構化日誌。 以下是之前使用的每個堆疊的最小範例。

保持自訂欄位簡潔且穩定（例如 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 ( slog )

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

記錄錯誤

若要在結構化日誌中擷取 兩者 錯誤訊息及其 堆疊追蹤，請發出包含標準欄位 (level, message) 加上 stack (或類似) 欄位的 JSON 記錄。

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 ( 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 和 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 建立執行層級。

如需在主控台中設定和啟動記錄的詳細資訊，請參閱 從主控台檢視應用程式、工作或功能記錄。