標準日誌行與結構化日誌

logging_instance 輸出固定的管線分隔人類字串,沒有 JSON 選項也沒有 trace/span 欄位,但 OTel 的 log-trace 關聯需要每筆記錄都帶 trace_id / span_id。本功能加入 Stripe 風格的標準日誌行(每次執行 輸出一個寬欄位包)以及一個攜帶 trace 脈絡的 JSON logging.Formatter。

純標準函式庫(json / logging);不匯入 PySide6。計時器時鐘可注入,因此時長在 CI 中具決定性。

無頭 API

from je_auto_control import (
    CanonicalLogLine, bind_trace_context, JSONLogFormatter,
    new_root_context,
)

line = CanonicalLogLine({"event": "run_suite"})
bind_trace_context(line, new_root_context())
with line.timer("execute"):
    run()
line.add("ok", True).emit(logger.info)         # 每次執行一行寬事件

# 帶 trace 關聯的結構化日誌:
handler.setFormatter(JSONLogFormatter())

CanonicalLogLine 累積請求範圍的欄位(add / update),透過 timer``(可注入時鐘)把一段區塊 計入 ``{name}_ms,並以 render / emit 將寬事件行輸出為 JSON。bind_trace_context 附上 SpanContext 的 trace_id / span_id。JSONLogFormatter 是一個 logging.Formatter,每筆記錄 輸出一個 JSON 物件,包含 trace_id / span_id 與任何 extra= 欄位 —— 與 trace_context 對應的 log-trace 關聯。

執行器命令

AC_canonical_log 從 fields 物件建立標準日誌行,回傳 {line, json}。它以 MCP 工具 ac_canonical_log 以及 Script Builder 中 Report 分類下的命令提供。