ingest_traces 工具詳解 · Codebase Memory

指令用途

靜態代碼分析（Static Analysis）雖然可以告訴我們程式碼「長什麼樣子」，但它完全無法得知程式碼「運行時的行為」。例如：一個看起來非常簡單的資料庫查詢方法，在執行期如果被調用了 10 萬次，或者在特定情況下產生了嚴重的延遲（Latency），這在靜態圖譜中是看不出來的。

ingest_traces 是 Codebase Memory 提供的動靜態結合高級分析工具。它能讀取標準的 OpenTelemetry JSON 格式 Trace 或日誌，將運行時的方法調用時長、頻次與異常（Exceptions）作為動態屬性，注入到靜態知識圖譜的對應 Method 節點上，幫助 AI 助手找出核心的性能瓶頸（Bottlenecks）。

運作流程

數據獲取：工具接收 OpenTelemetry JSON Trace 檔案路徑或 Trace 數據串流。
圖譜比對：解析 Trace 中的 Span 名稱（如 ControlSystem.Core.Communication.PlcConnection::ReadDeviceData），並與圖譜中的 Method 節點進行比對與綁定。
屬性注入：
- 將平均執行時長 avg_duration_ms 注入節點。
- 將呼叫次數 call_count 注入節點。
- 將運行時 Exception 記錄注入。
生成瓶頸報告：回傳受影響的節點分析。

實戰對話範例

範例：匯入 Trace 排查生產環境 PLC 讀取遲緩問題

You:

/opsx:explore "我們收到了生產環境的效能警報，PLC 讀取有嚴重延遲。請幫我匯入 otelemetry.json 並分析。"

AI:
好的，為了找出效能瓶頸，我將呼叫 ingest_traces 工具，將生產環境的運行期 Trace 數據與我們的代碼圖譜相結合。

CM 呼叫: ingest_traces(filePath: "temp/otelemetry.json")
CM 回傳:
```
{
  "status": "ingested",
  "spansProcessed": 482,
  "matchedNodes": 14,
  "performanceIssues": [
    {
      "method": "ControlSystem.Core.Communication.PlcConnection.ReadDeviceData",
      "calls": 12000,
      "avgDurationMs": 480,
      "issue": "HOT_PATH_DETECTED: 該方法平均延遲達 480ms，且被高頻率調用，佔用了 82% 的通訊時間。"
    }
  ]
}
```
分析：
透過動靜態融合分析，瓶頸非常明確： ReadDeviceData 在運行期平均花費了 480 毫秒，且在短短 5 分鐘內被調用了 12,000 次！這說明系統中存在頻繁且冗餘的輪詢，或者缺乏快取機制。

接下來，您希望我們在 PollPlcJob.cs 中加入快取機制，還是優化 PlcConnection 的讀取邏輯？