跳到內容

讓模組輸出日誌

文件對應版本v0.2.0/main 穩定版

接續第一個 RPC,這次替發送端與接收端加上日誌,記錄模組正在做什麼。日誌分成四個等級:

等級 適合記錄什麼 本篇範例
Debug 除錯時才需要的細節 準備發送訊息
Info 一般運作 模組啟動、收到訊息
Warn 可以繼續運作的異常情況 收到不認識的指令
Error 某個操作失敗 RPC 請求失敗

本篇使用 logPublisher、logSubscriber,實例名稱仍是 sender、receiver,收發訊息與 RPC 指令也和前面相同。

在模組內呼叫 context.log.write(等級, 文字) 即可寫入日誌。兩個模組都把這個操作放在一個具名函式裡:

logging/publisher.cpp
void write_log(vinc::log::Level level, std::string_view text) {
// 寫入一筆日誌;寫入被拒絕時提示錯誤,讓模組繼續運行。
auto logged = context.log.write(level, text);
if (!logged) {
std::cerr << "Log rejected: " << vinc::error_to_string(logged.error()) << std::endl;
}
}

logging/publisher.cpp · e165aed · 中文註解

如果日誌寫入被拒絕,函式會透過一般輸出提示,讓日誌失敗不會中斷訊息處理。

例如,接收端收到訊息時,寫入一筆 Info 日誌:

logging/subscriber.cpp
void on_message(std::unique_ptr<vinc::CounterSample> message) {
// 訂閱 callback:計數訊息送達時,由框架呼叫。
++received_;
write_log(vinc::log::Level::Info,
"counter received sequence=" + std::to_string(message->data().sequence.get()));
std::cout << "received sequence=" << message->data().sequence.get()
<< " publisher=" << message->publisher_name() << std::endl;
}

logging/subscriber.cpp · e165aed · 中文註解

原本的終端機輸出也保留,所以關閉日誌顯示後,仍能看到指令的執行結果。

在 open-vinc-examples 根目錄,重新建置前面準備好的專案。若上一個 Vinc Shell 還開著,先輸入 exit 關閉。

終端機視窗
cmake --build build/debug
.\build\debug\Vinc.exe

看到 VINC ready 後,在 Vinc Shell 輸入:

log show on

日誌顯示預設關閉。這行會開啟目前 Shell 的日誌顯示,預設等級為 Info,會顯示 Info、Warn 和 Error。

先啟動接收端:

logSubscriber

等到 Started receiver,再啟動發送端:

logPublisher

等到 Started sender。你也會看到包含 level=INFO 與 receiver started 或 sender started 的日誌,每筆都附有模組名稱與時間。

接著發送一筆訊息:

sender send

等待 received sequence=1 publisher=sender。接收端也會記錄一筆包含 counter received sequence=1 的 Info 日誌。

再輸入 sender count,發送端會記錄 RPC count=1,並印出熟悉的 RPC received=1。

模組預設略過 Debug 日誌。想看發送端的細節,需要同時調整來源等級和 Shell 顯示等級:

log level sender debug
log show debug
sender trace

sender trace 是本範例用來寫入 Debug 日誌的指令。等待 trace debug_enabled=1,以及包含 level=DEBUG 和 trace detail 的日誌。

來源等級會非同步套用。如果先看到 trace debug_enabled=0,稍候再輸入一次 sender trace。

兩個設定控制不同的事情:

指令 改變什麼
log level sender debug 發送端會產生哪些等級的日誌
log show debug 目前 Shell 會顯示哪些等級的日誌

只改 log show debug,看不到模組已經略過的 Debug 日誌。Debug 包含四種等級;Info 排除 Debug;Warn 只保留 Warn、Error;Error 只保留 Error。

保留發送端的 Debug 來源等級,把 Shell 顯示範圍縮小:

log show warn
sender invalid

會看到包含 unknown sender command 的 Warn 日誌,以及指令用法提示。

接著,故意向不存在的模組發出請求:

sender count missingReceiver

會看到包含 RPC request failed: 的 Error 日誌。Error 記錄這次操作失敗,不會讓模組停止。再輸入 sender count,仍能從真正的接收端取得 RPC received=1。

此時 Shell 已隱藏 Info、Debug 日誌,但 RPC received=1 這類一般指令輸出仍會顯示。

想在目前 Shell 隱藏日誌,可以輸入:

log show off

這只關閉顯示,日誌仍會收集並寫入檔案。最後輸入:

exit

等待模組停止並回到 PowerShell。

日誌檔案放在哪裡?

預設寫入 <執行檔目錄>/vinc_data/<VINC_NAME>/logs/,並依日期分資料夾。本篇範例對應:

  • C++:build/debug/vinc_data/counter-example/logs/
  • Python:build/python/vinc_data/python-tutorials/logs/

在 Vinc Shell 輸入 log status 可查看檔案輸出狀態。顯示過濾不會移除檔案中的日誌;來源過濾則是在收集前就略過該等級的日誌。