NotesLog：LotusScript Agent 的 Production Logging

2026.06.07 約 462 字

你的 scheduled agent 每天跑、但偶爾出問題你完全不知道 — 沒有 log、只能等使用者抱怨才發現。用 Print 語句記訊息？在 Notes Client 的 debug 視窗能看到、但 server 上跑的 scheduled agent 完全不記錄。

NotesLog 是 Domino 內建的 logging class — 幾行 code 就能把 agent 的執行過程記到 agent log、指定 NSF 資料庫、磁碟檔案、或寄郵件。這篇把它完整拆一遍。

重點摘要

NotesLog 用 New NotesLog("程式名稱") 建立
四種 Open：OpenAgentLog（記到 agent 自己的 log）/ OpenFileLog（寫檔、只在 client）/ OpenMailLog（關閉時寄郵件）/ OpenNotesLog（記到 NSF）
最常用的是 OpenAgentLog — 記到 agent 設計元件的 log、Admin Client 可查
LogAction(msg) 記一般動作、LogError(errNum, errMsg) 記錯誤
NumActions / NumErrors：計數唯讀屬性
Close() 結束 log 並把 mail log 寄出（OpenMailLog 時）
OverwriteFile：True 覆蓋舊 log 檔、False（預設）附加

建立 NotesLog 物件

' 建立 log 物件、傳入程式名稱（顯示在 log 裡）
Dim log As New NotesLog("OrderProcessor")

' 開啟 Agent Log（最常用）
Call log.OpenAgentLog()

建立後、必須呼叫一個 Open 方法才能開始記 log。沒有 Open 就呼叫 LogAction 會拋錯。

四種 Open 方式

1. OpenAgentLog — 記到 agent 自己的 log（推薦）

Call log.OpenAgentLog()

記錄到 agent 設計元件的 log 文件裡、在 Domino Designer 的 Agent properties 可以查、Admin Client 也可以查。Production agent 的標準作法。

2. OpenNotesLog — 記到指定 NSF

' 把 log 記到 logs.nsf 資料庫裡
Call log.OpenNotesLog("LogServer/ACME", "logs.nsf")

集中 log 管理時用。logs.nsf 用 Domino Log（log.ntf）模板建。

3. OpenMailLog — 關閉時寄郵件

' log 關閉時把所有記錄寄到指定信箱
Call log.OpenMailLog(Array("admin@acme.com"), "OrderProcessor 執行結果")

適合「只在出問題時才需要有人看」的批次 agent — 沒錯誤就不寄（因為 LogError 為 0）。

4. OpenFileLog — 寫磁碟檔案（只在 client）

' 只在 Notes Client 跑的 agent 可用（server 端會拋錯）
log.OverwriteFile = True  ' 每次覆蓋
Call log.OpenFileLog("C:\Logs\order_processor.log")

⚠️ OpenFileLog 不能在 server agent 用、呼叫會拋錯。

記錄 Action 跟 Error

' 記一般動作
Call log.LogAction("開始處理訂單批次")
Call log.LogAction("處理訂單 #" & orderNum & " 完成")

' 記錯誤（通常在 On Error 裡）
On Error GoTo ErrHandler
' ... 可能出錯的程式碼 ...
Exit Sub

ErrHandler:
    Call log.LogError(Err, Error())
    Resume Next

LogAction 的訊息長度沒有嚴格限制、但太長的訊息在 agent log 裡可能被截斷。

NumActions / NumErrors — 計數

' 執行完後報告
Print "共記錄 " & log.NumActions & " 個動作"
Print "共記錄 " & log.NumErrors & " 個錯誤"

' 根據錯誤數決定要不要發警告
If log.NumErrors > 0 Then
    ' 發警告郵件或記到另一個 log
End If

Production Agent 完整範本

可以直接拿來用的 agent logging 結構：

Sub Initialize
    Dim log As New NotesLog("OrderProcessor")
    Call log.OpenAgentLog()
    Call log.LogAction("=== 開始執行 ===")

    Dim session As New NotesSession
    Dim db As NotesDatabase
    Set db = session.CurrentDatabase

    On Error GoTo ErrHandler

    ' 主要邏輯
    Dim docs As NotesDocumentCollection
    Set docs = db.Search("Type = ""Order"" & Status = ""New""", Nothing, 0)
    Call log.LogAction("找到 " & docs.Count & " 筆待處理訂單")

    Dim doc As NotesDocument
    Set doc = docs.GetFirstDocument()
    Dim processed As Integer
    processed = 0

    Do Until doc Is Nothing
        On Error GoTo DocErrHandler
        ' 處理每筆文件
        doc.ReplaceItemValue "Status", "Processed"
        Call doc.Save(True, False)
        processed = processed + 1
        On Error GoTo ErrHandler

        Set doc = docs.GetNextDocument(doc)
    Loop

    Call log.LogAction("成功處理 " & processed & " 筆訂單")
    GoTo Done

DocErrHandler:
    Call log.LogError(Err, "處理文件時出錯：" & Error())
    Resume Next

ErrHandler:
    Call log.LogError(Err, Error())

Done:
    Call log.LogAction("=== 執行完畢（" & log.NumErrors & " 個錯誤）===")
    Call log.Close()
End Sub

LogErrors / LogActions 屬性（開關 log 類型）

' 不想記 action、只記錯誤
log.LogActions = False
log.LogErrors = True

LogActions / LogErrors 預設都是 True。在非常高頻的 agent 裡、可以只開 LogErrors 減少 log 量（LogError 方法說明）。

同類別在其他語言

語言	對應
LotusScript	`NotesLog`
Java	`lotus.domino.Log`（去掉 Notes 前綴、用完要 `.recycle()`）
SSJS	`Log`（XPages 內可呼叫、API 一致）

參考來源

← 回到文章列表