類別 Logger

Logger 類別提供一個簡單但精密的記錄公用程式，您可以使用它為您的程式建立一個或多個 事件記錄。每個此類記錄都包含一個時間順序的項目序列，提供程式活動的記錄。

關於範例¶ ↑

此頁面上的所有範例都假設已載入 Logger

require 'logger'

概要¶ ↑

使用 Logger.new 建立記錄

# Single log file.
logger = Logger.new('t.log')
# Size-based rotated logging: 3 10-megabyte files.
logger = Logger.new('t.log', 3, 10485760)
# Period-based rotated logging: daily (also allowed: 'weekly', 'monthly').
logger = Logger.new('t.log', 'daily')
# Log to an IO stream.
logger = Logger.new($stdout)

使用 Logger#add 新增項目（層級、訊息）

logger.add(Logger::DEBUG, 'Maximal debugging info')
logger.add(Logger::INFO, 'Non-error information')
logger.add(Logger::WARN, 'Non-error warning')
logger.add(Logger::ERROR, 'Non-fatal error')
logger.add(Logger::FATAL, 'Fatal error')
logger.add(Logger::UNKNOWN, 'Most severe')

使用 Logger#close 關閉記錄

logger.close

項目¶ ↑

您可以使用 Logger#add 方法新增項目

logger.add(Logger::DEBUG, 'Maximal debugging info')
logger.add(Logger::INFO, 'Non-error information')
logger.add(Logger::WARN, 'Non-error warning')
logger.add(Logger::ERROR, 'Non-fatal error')
logger.add(Logger::FATAL, 'Fatal error')
logger.add(Logger::UNKNOWN, 'Most severe')

這些簡寫方法也會新增項目

logger.debug('Maximal debugging info')
logger.info('Non-error information')
logger.warn('Non-error warning')
logger.error('Non-fatal error')
logger.fatal('Fatal error')
logger.unknown('Most severe')

當您呼叫這些方法中的任何一個時，項目可能會寫入記錄，也可能不會，這取決於項目的嚴重性以及記錄層級；請參閱 記錄層級

項目永遠有

• 嚴重性（add 的必要引數）。

• 自動建立的時間戳記。

也可能會有

• 訊息。

• 程式名稱。

範例

logger = Logger.new($stdout)
logger.add(Logger::INFO, 'My message.', 'mung')
# => I, [2022-05-07T17:21:46.536234 #20536]  INFO -- mung: My message.

條目的預設格式為

"%s, [%s #%d] %5s -- %s: %s\n"

其中要格式化的值為

• 嚴重性（一個字母）。

• 時間戳記。

• Process ID。

• 嚴重性（字詞）。

• 程式名稱。

• 訊息。

您可以透過下列方式使用不同的條目格式

• 設定自訂格式 proc（影響後續條目）；請參閱 formatter=。

• 使用區塊呼叫上述任何方法（僅影響單一條目）。這麼做有兩個好處

  • 內容：區塊可以評估整個程式內容並建立與內容相關的訊息。

  • 效能：除非記錄等級允許實際寫入條目，否則不會評估區塊

    logger.error { my_slow_message_generator }
    

    與字串形式形成對比，其中字串會始終評估，與記錄等級無關

    logger.error("#{my_slow_message_generator}")
    

嚴重性¶ ↑

記錄條目的嚴重性有兩個影響

• 決定是否選取條目納入記錄；請參閱 記錄等級。

• 向任何記錄讀取器（無論是人或程式）顯示條目的相對重要性。

時間戳記¶ ↑

記錄條目的時間戳記會在建立條目時自動產生。

記錄的時間戳記會使用此格式字串，由方法 Time#strftime 格式化

'%Y-%m-%dT%H:%M:%S.%6N'

範例

logger = Logger.new($stdout)
logger.add(Logger::INFO)
# => I, [2022-05-07T17:04:32.318331 #20536]  INFO -- : nil

您可以使用方法 datetime_format= 設定不同的格式。

訊息¶ ↑

訊息是條目方法的選用引數

logger = Logger.new($stdout)
logger.add(Logger::INFO, 'My message')
# => I, [2022-05-07T18:15:37.647581 #20536]  INFO -- : My message

對於預設條目格式器 Logger::Formatter，訊息物件可能是

• 字串：照樣使用。

• 例外狀況：使用 message.message。

• 其他任何內容：使用 message.inspect。

注意：Logger::Formatter 沒有跳脫或清除傳遞給它的訊息。開發人員應注意訊息中可能包含惡意資料（使用者輸入），並應明確跳脫不可信賴的資料。

您可以使用自訂格式器跳脫訊息資料；請參閱 formatter= 的範例。

程式名稱¶ ↑

程式名稱是條目方法的選用引數

logger = Logger.new($stdout)
logger.add(Logger::INFO, 'My message', 'mung')
# => I, [2022-05-07T18:17:38.084716 #20536]  INFO -- mung: My message

新記錄器的預設程式名稱可以在呼叫 Logger.new 時透過選用關鍵字引數 progname 設定

logger = Logger.new('t.log', progname: 'mung')

現有記錄器的預設程式名稱可以透過呼叫方法 progname= 設定

logger.progname = 'mung'

目前的程式名稱可以使用 progname 方法來取得

logger.progname # => "mung"

記錄等級¶ ↑

記錄等級設定決定是否實際將一個項目寫入記錄中，根據項目的嚴重性。

以下為已定義的嚴重性（從最不嚴重到最嚴重）

logger = Logger.new($stdout)
logger.add(Logger::DEBUG, 'Maximal debugging info')
# => D, [2022-05-07T17:57:41.776220 #20536] DEBUG -- : Maximal debugging info
logger.add(Logger::INFO, 'Non-error information')
# => I, [2022-05-07T17:59:14.349167 #20536]  INFO -- : Non-error information
logger.add(Logger::WARN, 'Non-error warning')
# => W, [2022-05-07T18:00:45.337538 #20536]  WARN -- : Non-error warning
logger.add(Logger::ERROR, 'Non-fatal error')
# => E, [2022-05-07T18:02:41.592912 #20536] ERROR -- : Non-fatal error
logger.add(Logger::FATAL, 'Fatal error')
# => F, [2022-05-07T18:05:24.703931 #20536] FATAL -- : Fatal error
logger.add(Logger::UNKNOWN, 'Most severe')
# => A, [2022-05-07T18:07:54.657491 #20536]   ANY -- : Most severe

預設的初始等級設定為 Logger::DEBUG，最低等級，表示寫入所有項目，不論嚴重性

logger = Logger.new($stdout)
logger.level # => 0
logger.add(0, "My message")
# => D, [2022-05-11T15:10:59.773668 #20536] DEBUG -- : My message

您可以在新的記錄器中使用關鍵字參數 level 和適當的值來指定不同的設定

logger = Logger.new($stdout, level: Logger::ERROR)
logger = Logger.new($stdout, level: 'error')
logger = Logger.new($stdout, level: :error)
logger.level # => 3

使用此等級，嚴重性為 Logger::ERROR 和更高的項目會被寫入，而嚴重性較低的項目則不會被寫入

logger = Logger.new($stdout, level: Logger::ERROR)
logger.add(3)
# => E, [2022-05-11T15:17:20.933362 #20536] ERROR -- : nil
logger.add(2) # Silent.

您可以使用 level= 方法為現有的記錄器設定記錄等級

logger.level = Logger::ERROR

以下簡寫方法也會設定等級

logger.debug! # => 0
logger.info!  # => 1
logger.warn!  # => 2
logger.error! # => 3
logger.fatal! # => 4

您可以使用 level 方法來取得記錄等級。

logger.level = Logger::ERROR
logger.level # => 3

以下方法會傳回是否寫入指定的等級

logger.level = Logger::ERROR
logger.debug? # => false
logger.info?  # => false
logger.warn?  # => false
logger.error? # => true
logger.fatal? # => true

記錄 File 輪替¶ ↑

預設情況下，記錄檔是一個會無限增長的單一檔案（直到明確關閉）；沒有檔案輪替。

為了讓記錄檔保持在可管理的大小，您可以使用 記錄 檔案 輪替，它會使用多個記錄檔

• 每個記錄檔都有不重疊時間區間的項目。

• 只有最近的記錄檔是開啟且作用中的；其他記錄檔是關閉且不作用的。

基於大小的輪替¶ ↑

對於基於大小的記錄檔輪替，請使用下列參數呼叫 Logger.new

• 參數 logdev 為檔案路徑。

• 參數 shift_age 為正整數：輪替中的記錄檔數量。

• 參數 shift_size 為正整數：每個記錄檔的最大大小（以位元組為單位）；預設為 1048576（1 百萬位元組）。

範例

logger = Logger.new('t.log', 3)           # Three 1-megabyte files.
logger = Logger.new('t.log', 5, 10485760) # Five 10-megabyte files.

對於以下範例，假設

logger = Logger.new('t.log', 3)

記錄開始於新的記錄檔 t.log；當新的項目會導致其大小超過 shift_size 時，記錄檔「已滿」且準備好輪替。

第一次 t.log 已滿時

• t.log 已關閉並重新命名為 t.log.0。

• 開啟新的檔案 t.log。

第二次 t.log 已滿

• +t.log.0 重新命名為 t.log.1。

• t.log 已關閉並重新命名為 t.log.0。

• 開啟新的檔案 t.log。

每次 t.log 已滿，日誌檔案會輪替

• t.log.1 已移除。

• +t.log.0 重新命名為 t.log.1。

• t.log 已關閉並重新命名為 t.log.0。

• 開啟新的檔案 t.log。

定期輪替¶ ↑

對於定期輪替，請使用字串週期指標呼叫 Logger.new。

• 參數 logdev 為檔案路徑。

• 引數 shift_age 為字串週期指標。

範例

logger = Logger.new('t.log', 'daily')   # Rotate log files daily.
logger = Logger.new('t.log', 'weekly')  # Rotate log files weekly.
logger = Logger.new('t.log', 'monthly') # Rotate log files monthly.

範例

logger = Logger.new('t.log', 'daily')

當給定的週期到期時

• 基本日誌檔案 t.log 會關閉並重新命名為基於日期的字尾，例如 t.log.20220509。

• 開啟新的日誌檔案 t.log。

• 不會移除任何項目。

字尾的預設格式為 '%Y%m%d'，會產生類似於上述的字尾。您可以使用建立時間選項 shift_period_suffix 設定不同的格式；請參閱 Time#strftime 中的詳細資料和建議。