MySQL DB LogWriter / TraceStore 邊界設計

返回

MySQL DB LogWriter / TraceStore 邊界設計

1. 文件目的

本文件承接 MySQL TaskStore command_executions 實作前確認，整理詳細診斷資料是否應由 DB LogWriter / TraceStore 承接，而不是直接塞入 MySqlTaskStore.Save(record)。

本文件只做邊界設計，不新增 table、不執行 DDL、不連真實 DB、不修改 ITaskStore / ILogWriter public method 簽章，也不修改 TaskExecutionRecord / TaskNodeExecutionRecord public constructor 或 property。

2. 目前已完成狀態

項目 狀態 說明
task_executions 已完成 MySqlTaskStore 已可保存任務主檔，並完成真實 DB manual-only 驗證。
node_executions 已完成 MySqlTaskStore 已可保存節點摘要，並完成真實 DB manual-only 驗證。
command_executions 尚未實作 已完成實作前確認，結論是不宜在資料來源未固定前直接塞入 TaskStore。
LogEntry 已存在 已包含 TaskId、NodeId、DeviceId、CommandName、RawRequestSummary、RawResponseSummary、AdapterTimeTakenMs、DataSummary、MetadataSummary、ErrorCode、Message。
ILogWriter 已存在 目前可由 Console / File / Memory writer 接收 LogEntry。
WorkflowEngine 已承接 Adapter Data 已把 Adapter result 的 RawRequest / RawResponse / Data / Metadata 轉成 summary 寫入 LogEntry。

3. 核心邊界結論

MySqlTaskStore 與 DB diagnostic log 應拆開。

元件 職責 不應負責
MySqlTaskStore 保存任務主檔與節點摘要，例如 task_executions、node_executions。 不保存完整診斷 log、不承擔 Raw payload 清理、不當作一般 log sink。
MySqlLogWriter 將 LogEntry 安全轉成 DB trace row。 不改變 Workflow 結果、不取代 Console / File log、不直接執行 schema apply。
TaskTraceStore 提供依 TaskId、NodeId、DeviceId、時間區間查詢 trace 的讀取介面。 不負責任務狀態轉換、不寫入 Workflow 核心狀態。
task_log_traces 保存任務與設備命令相關診斷摘要。 不替代 task_executions / node_executions / command_executions。

4. 為什麼建議走 Log 流

command_executions 若要保存 RawRequest / RawResponse，最完整的資料目前已在 LogEntry 與 Workflow snapshot 流中。

走 LogEntry -> MySqlLogWriter -> task_log_traces 的優點：

  1. 不需要為了診斷欄位修改 TaskExecutionRecord / TaskNodeExecutionRecord public model。
  2. 不會讓 MySqlTaskStore.Save(record) 同時承擔任務保存與大量 log sink。
  3. 可以獨立做 payload 遮蔽、長度限制、保留天數與查詢索引。
  4. DB log 寫入失敗時，可獨立處理，不必改變 Workflow 任務成功或失敗判斷。
  5. 未來若一個 node 執行多個 Adapter command，Log 流比 TaskStore node summary 更適合承接多筆診斷事件。

5. 建議資料流

WorkflowEngine
  -> LogEntry
  -> ILogWriter
      -> ConsoleLogWriter
      -> FileLogWriter
      -> MemoryLogWriter
      -> MySqlLogWriter
            -> task_log_traces

TaskTraceStore
  -> query task_log_traces by TaskId / NodeId / DeviceId / time range

第一版建議 MySqlLogWriter 是可選 writer，不得取代既有 Console / File / Memory writer。

6. 建議 table 定位：task_log_traces

task_log_traces 應定位為「診斷 trace table」，不是任務主檔，也不是命令執行表。

6.1 欄位草案

以下只是設計草案，尚未確認前不得建立 table。

欄位 型別 必填 來源 說明
trace_id varchar(64) 是 寫入端產生 Trace 主鍵，避免依賴 DB 自動編號造成測試不易比對。
task_id varchar(64) 否 LogEntry.TaskId 任務識別碼。
node_id varchar(64) 否 LogEntry.NodeId Workflow 節點識別碼。
node_name varchar(128) 否 LogEntry.NodeName Workflow 節點名稱。
device_id varchar(64) 否 LogEntry.DeviceId 設備識別碼。
command_name varchar(128) 否 LogEntry.CommandName Adapter 命令名稱。
level varchar(32) 是 LogEntry 或 writer mapping Log level，第一版可先以 Info / Warning / Error 表示。
status varchar(32) 否 LogEntry.Status 任務、節點或命令狀態。
retry_count int 否 LogEntry.RetryCount 節點 retry count。
time_taken_ms int 否 LogEntry.TimeTakenMs 節點或事件耗時。
adapter_time_taken_ms int 否 LogEntry.AdapterTimeTakenMs Adapter 命令耗時。
error_code varchar(64) 否 LogEntry.ErrorCode 錯誤代碼。
message varchar(255) 否 LogEntry.Message 訊息摘要。
data_summary text 否 LogEntry.DataSummary Adapter Data 摘要。
raw_request_summary text 否 LogEntry.RawRequestSummary 已遮蔽與截斷後的 request 摘要。
raw_response_summary text 否 LogEntry.RawResponseSummary 已遮蔽與截斷後的 response 摘要。
metadata_summary text 否 LogEntry.MetadataSummary Metadata 摘要。
host_name varchar(128) 否 Host context 執行主機名稱。
operator_id varchar(64) 否 Host context 操作者或服務帳號。
app_version varchar(64) 否 Host context 程式版本。
created_at datetime 是 寫入當下 Trace 建立時間。

6.2 建議索引

Index Columns 用途
idx_task_log_traces_task_id task_id 查詢指定任務完整 trace。
idx_task_log_traces_node_id node_id 查詢特定節點 trace。
idx_task_log_traces_device device_id 查詢設備相關 trace。
idx_task_log_traces_command command_name 查詢命令相關 trace。
idx_task_log_traces_status status 查詢失敗或特定狀態 trace。
idx_task_log_traces_error_code error_code 查詢特定錯誤。
idx_task_log_traces_created_at created_at 依時間排序與清理。

7. MySqlLogWriter 寫入策略

第一版建議：

  1. MySqlLogWriter 只接收已產生的 LogEntry，不主動改 Workflow 狀態。
  2. 寫入前必須經過 payload sanitizer，避免保存 password、token、connection string 或完整敏感 payload。
  3. RawRequestSummary / RawResponseSummary 只保存摘要，不保存未遮蔽完整原文。
  4. 單筆寫入失敗時，不應讓 Workflow 任務結果由成功變失敗；但必須讓 host 或 fallback log 知道 DB log 寫入失敗。
  5. 第一版不做批次寫入、不做背景佇列、不做 retry worker，避免擴大到背景服務範圍。
  6. 第一版不自動建表，也不在 ConsoleHost 啟動時 apply schema。

8. TaskTraceStore 查詢策略

TaskTraceStore 建議作為讀取介面，不與 ITaskStore 混在一起。

建議第一版查詢能力：

查詢 用途
FindByTaskId(taskId) 查詢單一任務完整 trace。
FindByNodeId(taskId, nodeId) 查詢指定任務節點 trace。
FindByDeviceId(deviceId, from, to) 查詢設備在時間區間內的 trace。
ListRecentErrors(limit) 查詢最近錯誤 trace。

以上查詢介面若要實作，會新增 public contract，必須另做實作前確認。

9. 與 command_executions 的關係

task_log_traces 與 command_executions 不應互相取代。

Table 建議定位
command_executions 給報表或任務明細查詢使用的命令執行表，欄位較固定。
task_log_traces 給除錯與診斷使用的 log / trace 表，資料量較大，欄位偏診斷。

目前建議先做 task_log_traces 邊界設計，是因為 RawRequest / RawResponse 較接近診斷資料，不宜為了它先修改 TaskStore model。

若後續需要 command_executions，可以從 LogEntry 或 WorkflowNodeExecutionSnapshot 派生，但必須先做資料來源決策表。

10. Payload 安全規則

DB trace 不能直接保存未處理的 raw payload。

第一版 sanitizer 至少應處理：

規則 說明
長度限制 request / response summary 建議限制在固定字數，例如 2,000 或 4,000 字內。
敏感字遮蔽 password、token、secret、connection string、authorization 需遮蔽。
二進位摘要 若 payload 是 byte array，只保存 hex 摘要與長度，不保存完整大 payload。
Null 安全 沒有 raw data 時保存 null，不硬塞空字串。
錯誤可讀性 遮蔽後仍需保留足夠資訊判斷命令、裝置與錯誤原因。

11. 測試策略

11.1 自動測試

測試 目的
LogEntry to trace row mapper 測試 確認欄位來源正確，Raw summary 不遺失。
payload sanitizer 測試 確認敏感資訊被遮蔽，長字串會截斷。
SQL generator 測試 確認 task_log_traces schema class 可產生 MySQL 5.6.2 DDL preview。
fake gateway writer 測試 確認 MySqlLogWriter 寫入正確 SQL 與參數，不連真實 DB。
writer failure 測試 確認 DB log 寫入失敗不會改變 Workflow result。

11.2 manual-only 真實 DB 驗證

若後續完成實作，真實 DB 驗證需另列節點，且只能在使用者明確確認後執行：

  1. 確認測試 DB 與 table 已準備完成。
  2. 明確開啟 manual-only gate。
  3. 寫入成功、失敗、含 Raw summary、含 ErrorCode 的 trace rows。
  4. 依 TaskId 查回 trace。
  5. 驗證 index 與 comment。
  6. 驗證敏感資訊未被保存。
  7. cleanup 僅清除本次測試前綴資料。

12. 必須停下確認的事項

以下任一項出現時，Codex 必須停下，不得自動執行：

  1. 新增或修改 public contract，例如 ILogWriter、ITaskStore、TaskTraceStore 介面。
  2. 修改 TaskExecutionRecord / TaskNodeExecutionRecord public constructor 或 property。
  3. 建立 task_log_traces table 或執行任何 DDL / ALTER。
  4. 對真實 DB 執行未確認的 INSERT、UPDATE、DELETE。
  5. 把真實 DB 測試加入一般 CI。
  6. 保存 password、Token、完整 connection string 或未遮蔽 RawRequest / RawResponse。
  7. 導入背景佇列、ServiceHost、WebApi 或正式 DB 自動 apply 流程。
  8. 新增或更換 MySQL 套件。
  9. 讓 DB log 寫入失敗直接改變 Workflow 任務成功 / 失敗結果。

13. 建議結論

建議採用「TaskStore 保存任務與節點，DB LogWriter 保存診斷 trace」的切分。

目前不要把 command_executions 或詳細 Raw 診斷資料直接塞進 MySqlTaskStore.Save(record)；較安全的下一步是做「DB LogWriter / TraceStore 實作前確認」，先固定：

  1. task_log_traces schema class。
  2. LogEntry to trace row mapper。
  3. payload sanitizer 規則。
  4. fake gateway 測試策略。
  5. DB log 寫入失敗時的 fallback 行為。

確認後再進入第一版實作，仍維持不自動連真實 DB、不自動建表、不修改現有 TaskStore public contract。