六個方法

init

SDK 初始化。設定 collector endpoint、app 識別資訊、flush 間隔、buffer 大小。在 app 啟動時呼叫一次。

1Monitor.init({
2  endpoint: 'https://collector.example.com/v1/events',
3  app: 'my_app',
4  version: '1.2.0',
5  flushInterval: 30000,   // 毫秒
6  bufferSize: 100,
7})

init 負責建立 session、記錄 lifecycle.session.start 事件、啟動 flush 計時器。init 之前呼叫其他方法應該拋出明確錯誤（SDK 未初始化），而非靜默忽略。

連線驗證策略：lazy。init 不驗證 collector 是否可達 — 不發 HTTP 請求、不 ping endpoint。init 的失敗只代表配置錯誤（缺少 endpoint 參數），不代表網路問題。網路問題在第一次 flush 時才浮現，flush 失敗時事件保留在 buffer 等待重試。

Lazy 策略的理由：SDK 不應阻塞主程式的啟動流程。如果 init 驗證連線，collector 暫時不可用時 app 會啟動失敗 — 監控工具反而變成可用性的瓶頸。短生命週期腳本（Python 平台適配：短生命週期腳本）對這一點更敏感 — hook 腳本不能因為 collector 沒啟動就拒絕執行。

event

記錄使用者操作事件（四類事件中的 Event 類）。接受事件名稱和可選的 data 物件。

1Monitor.event('terminal.connect.start', { url: 'wss://...' })
2Monitor.event('enrollment.qr.scan')

event 方法是非阻塞的 — 事件進入內部 buffer 立即返回，不等待網路送出。應用程式的操作流程不應該被監控 SDK 的網路延遲阻塞。

error

記錄錯誤事件。接受 Error/Exception 物件或自訂的錯誤描述。自動附加 stack trace、錯誤類型、觸發位置。

1Monitor.error(exception, { step: 'ws_connect' })
2Monitor.error('Auth token missing', { context: 'handshake' })

error 方法和自動攔截機制（自動攔截）互補 — 自動攔截處理未捕獲的例外，error 方法處理開發者主動上報的已知錯誤。

metric

記錄數值指標。接受指標名稱和數值。

1Monitor.metric('connect.duration_ms', 320)
2Monitor.metric('terminal.fps', 58.5)

metric 方法記錄的是離散的數值快照。聚合計算（平均、百分位、趨勢）在 collector 端完成，SDK 端只負責記錄原始值。

flush

強制送出 buffer 中所有待發事件。正常情況下 SDK 按 flushInterval 定期自動 flush（攢批送出）。flush 方法用於需要確保事件已送出的場景 — 例如 app 即將進入背景或使用者手動觸發 log 上傳。

1await Monitor.flush()

flush 是非同步方法 — 需要等待網路請求完成。呼叫端可以 await 確認送出成功，也可以 fire-and-forget。

close

SDK 資源釋放。停止 flush 計時器、送出 buffer 中剩餘事件、關閉網路連線、記錄 lifecycle.session.end 事件。

1await Monitor.close()

close 在 app 關閉時呼叫。呼叫後 SDK 進入已關閉狀態，後續的 event/error/metric 呼叫應該被靜默忽略（不拋錯，因為 app 正在關閉）。

API 設計原則

方法名稱和四類事件對齊。event / error / metric 三個方法直接對應三類事件，lifecycle 事件由 init 和 close 自動產生。開發者看到方法名稱就知道對應哪類事件。

所有上報方法非阻塞。event、error、metric 進 buffer 立即返回。監控 SDK 阻塞應用程式的操作流程是反模式。

init 和 close 成對出現。init 開始 session，close 結束 session。兩者界定 SDK 的活躍期間。

各平台的 SDK 整合範例（Flutter 的 pubspec.yaml + main.dart init、Python 的 pip install + init code、JS 的 script tag + init）見 monitor repo 各 SDK 的 README。

下一步路由

• 自動攔截未捕獲的錯誤 → 自動攔截機制
• Buffer 和 flush 的策略 → 攢批送出策略
• SDK 端的資料脫敏 → SDK redaction helper
• SDK 的 HTTP POST 行為需要 protocol test → testing 模組三 協議整合測試

Event：使用者做了什麼

Event 記錄使用者主動發起的操作。按鈕點擊、頁面瀏覽、表單提交、搜尋查詢 — 每個 event 代表使用者的一個意圖表達。

Event 的觸發時機是使用者操作發生時。程式碼中的位置通常是 UI 事件處理器（onClick、onSubmit、onNavigate）。

Event 的消費方式：

• Debug context：問題發生前使用者做了哪些操作。和 error 事件搭配使用，還原問題的操作路徑。
• 行為分析：使用者做了哪些操作、操作順序是什麼、在哪一步停止。Funnel analysis 的原料（模組八）。
• 功能使用率：哪些功能被頻繁使用、哪些很少被觸發。功能優先順序的決策依據。

Error：什麼出了問題

Error 記錄程式碼執行中的非預期狀態。例外拋出、assertion 失敗、非預期的 API 回應、資源存取失敗。

Error 的觸發時機是非預期狀態被偵測到時。來源包括：語言層級的 try/catch 捕獲、框架的全域錯誤處理器（Flutter 的 FlutterError.onError、JavaScript 的 window.onerror）、自訂的錯誤檢查邏輯。

Error 的消費方式：

• 即時告警：特定類型的 error 或 error 數量超過閾值時通知開發者。
• 趨勢分析：error 數量隨時間的變化。新版本部署後 error 是否增加。
• 根因分析：error 的 stack trace、觸發條件、影響範圍。和 event 搭配還原「使用者做了什麼導致 error」。

Metric：系統狀態的數值快照

Metric 記錄系統狀態的可量化指標。回應時間、記憶體使用量、佇列長度、連線數、frame rate。

Metric 的觸發時機是定期取樣或特定事件發生時。定期取樣適合持續變化的指標（記憶體使用量每 30 秒取一次），事件觸發適合離散的測量（每次 API 回應記錄回應時間）。

Metric 的消費方式：

• 效能監控：回應時間的 P50 / P95 / P99 分佈。記憶體使用量的趨勢。
• 容量規劃：佇列長度接近上限、連線數接近 pool 上限 — 需要擴容的訊號。
• SLA 追蹤：服務可用性、回應時間是否在承諾範圍內。

Lifecycle：系統經歷了什麼階段

Lifecycle 記錄系統本身的狀態轉換。App 啟動、前景/背景切換、連線建立/斷開、版本更新、設定變更。

Lifecycle 的觸發時機是系統狀態轉換發生時。來源包括：app 生命週期回呼（onCreate、onResume、onPause）、連線狀態變化事件、部署和設定變更鉤子。

Lifecycle 的消費方式：

• Session 分析：使用者一次使用多久、啟動頻率、前後景切換頻率。
• 環境資訊：Error 發生時的系統狀態（app 版本、OS 版本、網路狀態）。
• 連線品質：連線建立成功率、斷線頻率、重連次數（testing 模組二 三層 log）。

四類事件的區別

下一步路由

• 事件命名規範 → 事件命名規範
• 從需求推導收集策略 → 從需求推導「該收集哪些事件」
• Event 類事件在商業分析中的用途 → 模組八 行為資料的商業利用
• Log 點的設計方法 → testing 模組二 客戶端可觀測性

Isolate 安全

Dart 的 Isolate 是獨立的記憶體空間，Isolate 之間不共享記憶體，只能透過 message passing 溝通。SDK 的記憶體 buffer 存在於 main isolate 中，其他 isolate 產生的事件需要透過 port 傳送到 main isolate 才能進入 buffer。

SDK 端的適配：

提供 Monitor.eventFromIsolate(SendPort port) 方法，在子 isolate 中透過 port 把事件送回 main isolate。或者提供 isolate-aware 的 Monitor.init() 變體，在子 isolate 中初始化一個輕量的 event forwarder。

如果 SDK 使用 compute 或 Isolate.spawn 做背景任務（例如壓縮 buffer），需要透過 port 把結果送回 main isolate — 背景 isolate 無法直接存取 main isolate 的 HTTP client 或 buffer。

Platform channel 攔截

Flutter 透過 Platform channel 呼叫原生平台功能（iOS 的 Swift/ObjC、Android 的 Kotlin/Java）。Platform channel 的呼叫可能失敗（原生端未實作、參數格式錯誤、原生端拋出例外），這些錯誤在 Dart 端表現為 PlatformException。

SDK 可以攔截 Platform channel 的呼叫記錄每次呼叫的方法名稱、參數、結果和耗時。攔截方式是替換 ServicesBinding.defaultBinaryMessenger 的處理器，在轉發前後記錄事件。

攔截的價值是：Platform channel 的錯誤通常難以 debug（stack trace 跨越 Dart 和原生兩層），監控記錄提供「呼叫了哪個 channel method、傳了什麼參數、在哪一層失敗」的完整 context。

注意：攔截 Platform channel 會增加每次呼叫的延遲（記錄事件的開銷）。對高頻的 Platform channel 呼叫（例如每幀都呼叫的渲染相關 channel），攔截可能影響效能。SDK 應該提供 channel 過濾機制 — 只攔截特定 channel 或只在 debug mode 攔截。

App lifecycle 事件

Flutter 的 WidgetsBindingObserver 提供 app 生命週期回呼：

• didChangeAppLifecycleState(AppLifecycleState state) — app 在 resumed（前景）、inactive（部分可見）、paused（背景）、detached（即將關閉）之間切換。

SDK 在 init 時註冊 observer，記錄每次狀態轉換為 lifecycle 事件。

lifecycle 事件在 flush 策略中有特殊意義：

paused（進入背景）：觸發 flush — 把 buffer 中的事件送出，因為 app 在背景可能被系統殺掉，buffer 中的事件會遺失。iOS 在 app 進入背景後約 5 秒 suspend，flush 必須在這個時間窗口內完成。

resumed（回到前景）：檢查上次 flush 是否成功。如果 paused 時的 flush 失敗（網路超時），在 resumed 時重試。

detached（即將關閉）：呼叫 Monitor.close() 做最後一次 flush 和資源釋放。detached 的時間窗口更短，close flush 可能被截斷。

下一步路由

• Python 平台的適配 → Python 平台適配
• 跨平台 timestamp 一致性 → 跨平台 timestamp 一致性
• 自動攔截機制 → 模組三 自動攔截

Lifecycle Contract

Lifecycle contract 定義平台如何啟動、檢查、接流量、停止與回收服務實例。它包含 runtime、startup、readiness、liveness、shutdown 與 drain。

這些狀態分開後，部署事故才能定位是啟動、接流量、退場還是平台判讀問題。

runtime 與 startup 決定服務能否形成可運行實例。readiness 與 liveness 決定平台何時導入流量與何時重建實例。shutdown 與 drain 決定版本退場時是否能保護在途工作。這些狀態都屬於生命週期合約，卻對應不同的事故處理路徑。

Startup 與 Readiness

startup 的責任是確認服務初始化完成。readiness 的責任是確認服務可承接實際流量。啟動完成不代表依賴已就緒，也不代表背景任務、config、secret 或 connection pool 都可用。

慢啟動服務需要 startup gate，避免 liveness 在初始化期間反覆重啟。依賴敏感服務需要 readiness gate，避免尚未連上資料庫、cache 或 queue 時就接收請求。

啟動時間的組成與壓縮

服務啟動時間的長短決定 rollout 節奏的下限。啟動時間由四段組成，每段有不同壓縮策略：

1. runtime 初始化：語言 VM、GC 初始化、class loading（JVM warmup 可達 10-30 秒）。壓縮手段是 ahead-of-time compilation（GraalVM native image、Go 靜態編譯啟動速度快）或 CDS（Class Data Sharing）。
2. 依賴建立：資料庫連線池、cache 連線、queue consumer 註冊。壓縮手段是 lazy initialization（按需建立）或 connection pool pre-warming（啟動時建好但不阻擋 readiness）。
3. 資料預載：config 同步、feature flag 初始拉取、本地快取預熱。壓縮手段是區分必要載入與非必要載入——必要的阻擋 readiness，非必要的平行載入。
4. 就緒驗證：自我健康檢查、依賴可達性驗證。壓縮手段是平行驗證多個依賴，避免串行等待。

啟動時間超過平台預設 startup timeout 時，先拆成這四段分析瓶頸，再決定調大 timeout 還是壓縮啟動流程。盲目調大 timeout 會掩蓋啟動退化問題，讓單次 rollout 的最短觀察窗拉長。

Readiness 設計的核心取捨

readiness 太鬆（只檢查 HTTP port 是否可達）會讓尚未就緒的實例接到流量。readiness 太緊（檢查所有下游可達性）會讓非自身問題的下游故障觸發連鎖 not-ready，放大故障面。

取捨的判讀框架是「這個依賴不可用時，服務是否仍能提供有意義的回應」：

• 必要依賴：資料庫、auth service——不可用時服務完全無法處理請求。這類依賴的可達性應納入 readiness 條件。
• 可降級依賴：推薦引擎、非關鍵 cache——不可用時服務可回傳降級結果。這類依賴不應納入 readiness，改用 circuit breaker 或 fallback 處理。
• 觀測依賴：metrics collector、log shipper——不可用不影響業務流量。這類依賴進 readiness 是常見誤判，會讓觀測基礎設施故障擊倒整個服務。

對應 5.C3 Orbitera managed K8s migration：揭露「跨平台遷移本質是能力遷移、部署 / 觀測 / 恢復與團隊流程都需要同步重建」。遷移到新平台時，舊平台的 readiness 條件不能直接搬——新平台的依賴可達路徑、DNS 解析速度、secret 注入方式可能改變，readiness 條件要重新驗證。

Liveness 與 Restart

liveness 的責任是偵測無法自我恢復的狀態。短暫下游故障適合交給 readiness、circuit breaker 或 fallback 處理，否則平台會用重啟放大故障。

liveness 太敏感會造成 restart loop；liveness 太寬鬆會讓壞實例長期留在線上。設計時要先定義哪些錯誤可由服務內部恢復，哪些才需要平台重建。

Liveness 適合偵測的失敗模式

liveness 的工程價值在於捕捉服務自己無法修復的狀態。把 liveness 當成通用健康檢查是過度使用，會讓正常的瞬態故障觸發不必要的重建。

適合 liveness 偵測的狀態：

• deadlock：所有 worker thread 被卡住，無法處理新請求也無法回傳錯誤。liveness endpoint 設在獨立 goroutine / thread 上，如果 worker pool 卡住但 liveness goroutine 能回應，問題在業務邏輯而非 deadlock。
• memory leak 導致的 OOM 前兆：記憶體使用率持續上升不回落，GC 已無法回收。此時主動回報 unhealthy 讓平台在 OOM kill 前重建，比被動等 OOM 更可控——OOM kill 不走 graceful shutdown，在途請求直接中斷。
• essential background task 永久停止：必要的定期任務（如 license renewal、session cleanup）超過預期間隔仍未執行。這類失敗靜默發生，只有 liveness 主動偵測能發現。

不適合 liveness 偵測的狀態：下游資料庫短暫不可用、外部 API timeout、cache miss 率升高。這些由 readiness 或 circuit breaker 處理——用 liveness 重建不會修好下游，只會用重啟放大問題。

Restart 的代價量化

每次 liveness 觸發的重啟會產生四類代價：

1. 在途請求中斷：被重啟的實例正在處理的請求直接失敗。
2. 連線重建成本：資料庫連線池、cache 連線、queue consumer 重新建立。
3. 啟動期間的容量缺口：重啟到 readiness 通過之間，整體服務容量降低。
4. thundering herd 風險：多實例同時被 liveness 判定失敗並重啟時，同時重建連線、同時搶資源、下游壓力瞬間放大。

對應 5.C7 Airbnb Istio 升級治理：揭露「基礎平台元件升級若缺乏分批治理、會形成全域風險放大器」。以下基於通用工程知識展開：Istio 等 service mesh 升級期間的 sidecar 重啟可觸發大量服務的 liveness 暫時失敗，若 liveness 太敏感會放大成全域 restart storm。升級期的 liveness 閾值應比穩態更寬鬆，或在升級批次中暫時加大 liveness failure threshold。

Shutdown 與 Drain

shutdown 的責任是讓服務停止接新工作並完成資源釋放。draining 的責任是讓平台在移除實例前，讓 in-flight request、長連線或背景工作有時間收束。

短 request API、長連線服務與 background worker 的 drain 條件不同。短 API 主要看在途請求歸零；長連線看 reconnect 節奏；worker 看已領取工作能否完成或重新排隊。tunnel 入口的 startup / readiness / drain 對齊見 5.10 Outbound Tunnel 入口。

三種 Workload 的 Drain 差異

不同 workload 類型的 drain 完成條件與時間尺度完全不同，用同一套 drain 設定覆蓋所有 workload 會在至少一類服務上出事。

短 request API（HTTP REST、gRPC unary）：drain 窗口通常在 5-30 秒。核心條件是在途請求數歸零。風險點是 load balancer 的 deregistration delay——LB 可能在服務已標記 not-ready 後仍送幾秒流量（取決於 health check interval 與 deregistration delay），所以服務端 drain 窗口要覆蓋這段延遲。endpoint 摘除的傳播窗口與 preStop 等待策略見 5.4 摘除節奏與 Drain 的配合。

長連線服務（WebSocket、gRPC streaming、SSE）：drain 窗口通常在 30 秒到數分鐘。核心條件是現有連線收斂且 reconnect 波形穩定。風險點是客戶端 reconnect 策略——服務端 drain 完成不代表客戶端已連上新實例。若客戶端沒有 backoff 或 reconnect 目標選擇邏輯，會形成 reconnect storm。drain 設計要跟客戶端 reconnect 策略一起規劃。

Background worker（queue consumer、定時任務、batch job）：drain 窗口取決於單一工作的最長執行時間。核心條件是已領取的工作完成處理或安全重新排隊。風險點是不可中斷工作——某些 job 做到一半無法重試（例如外部 API 呼叫已發出但回應尚未確認），drain 時序要覆蓋這類 job 的最長完成時間，否則 job 被中斷後產生不一致狀態。

對應 5.C9 反例：平台切流未先 Draining：揭露「切流失敗常在 connection lifecycle 管理」「drain / idle timeout / health check / client retry 沒有同一節奏」。反例中的事故擴大機制正是不同 workload 類型的 drain 條件被忽略——短 API 的 drain 完成了，長連線的 reconnect 仍在震盪，worker 的 job 被中斷重試造成重複處理。

Shutdown 信號的傳遞路徑

platform 到 application 的 shutdown 信號傳遞有多個可能斷點。信號從平台送到容器 PID 1、PID 1 轉發到應用進程——PID 1 的信號處理語意與常見陷阱見 5.1 PID 1 與信號處理。本段聚焦 lifecycle 層的時序問題：

• preStop hook 與 SIGTERM 時序：Kubernetes 先執行 preStop hook、再送 SIGTERM。preStop hook 可用來等 LB 摘流量（sleep 幾秒讓 endpoint 從可用集合移除），讓 SIGTERM 到達時在途流量已經減少。
• terminationGracePeriodSeconds：平台等待的最長時間。超過後 SIGKILL 強制結束，不走 graceful shutdown。這個值要覆蓋 preStop + drain + 資源釋放的總時間。

shutdown 信號傳遞的驗證方式是在 staging 環境觸發 pod delete，觀察應用 log 中是否出現 shutdown handler 的紀錄。沒看到 shutdown log 代表信號沒傳到、要先修傳遞路徑再談 drain 設計。

不同 Workload 的 Lifecycle 特性對照

生命週期合約的參數設定要依 workload 類型調整。以下是三類常見 workload 的特性差異。

這張表是選型前判準的操作化：先確認服務屬於哪類 workload，再套用對應的 lifecycle 參數基線。混合 workload（例如同時提供 HTTP API 和 WebSocket）要取各層的嚴格值——drain 窗口取最長的、readiness 取最嚴格的。

平台如何表達 Lifecycle 差異

不同部署平台表達生命週期合約的能力不同。選型時要問的是「這個平台能不能分別設定 startup、readiness、liveness 與 drain」。

Kubernetes 在 lifecycle 表達力上最完整，但參數最多也最容易配錯。systemd 靠 sd_notify 協議明確宣告 readiness，在單機部署場景下反而比 K8s 的 probe 直接。Docker 和 ECS 不分離 readiness 與 liveness，需要在應用層自行實作降級邏輯。

選平台不只看功能清單，要看它表達 lifecycle 差異的粒度是否覆蓋服務需求。若服務需要分離 startup 和 readiness 但平台只有一個 health check，這個差距要在應用層補——代價是複雜度從平台設定轉移到程式碼。

遷移期的 Lifecycle 重新驗證

對應 5.C6 Airbnb Kubernetes 叢集擴縮演進：揭露「擴縮策略版本化與可回放」「不同 workload 區分擴縮政策」。以下基於通用工程知識展開：叢集演進過程中，lifecycle 參數的假設會改變——workload 從穩態變成高波動、從單一類型變成混合類型、從小規模變成大規模。lifecycle contract 的參數不是設一次就好，要隨叢集演進重新驗證。

對應 5.C10 對照：規模差異下的平台遷移：揭露「小型組織最容易漏掉回退腳本化」「中型組織依賴錯位、服務切過去但資料面 / 認證面 / 觀測面沒同步」。lifecycle contract 在遷移後的完整性驗證不只看 probe 設定——secret 注入時序、資料庫連線池的 endpoint 是否切到新叢集、observability pipeline 的 readiness 是否對齊，都是 lifecycle 合約的一部分。

遷移後的 lifecycle 驗證清單：

1. startup 時序重測：新平台的 image pull 時間、secret mount 時間、DNS 解析路徑可能不同，原本的 startup timeout 可能不夠。
2. readiness 依賴路徑檢查：readiness 檢查的依賴是否仍可達（新叢集到舊資料庫的 latency 是否增加、跨叢集 service discovery 是否對齊、DNS TTL 與快取行為是否改變）。
3. drain 行為驗證：在新平台觸發 pod delete、觀察 drain 完成時間與在途請求處理是否符合預期。
4. 信號傳遞驗證：在新平台觸發 shutdown、確認 SIGTERM 到達應用進程並觸發 graceful shutdown handler。

選型前判準

部署平台選型前要先回答：

1. 服務啟動需要多久，哪些依賴是 readiness 條件。
2. 服務失敗時應由自己恢復，還是由平台重建。
3. 服務停止時有哪些 in-flight request、connection 或 job。
4. 平台是否能表達 startup、readiness、liveness 與 drain 的差異。

這些問題決定後續要比較 Kubernetes probe、systemd restart policy、load balancer health check 或 service mesh drain 能力。

判讀訊號

常見誤區

把所有 probe 設成同一個 /health endpoint，會讓 startup、readiness 與 liveness 的語意混在一起。三種 probe 回答不同問題：startup 問「初始化完了嗎」、readiness 問「可以接流量嗎」、liveness 問「還活著嗎」。同一個 endpoint 無法同時回答三個問題，因為初始化完成不代表依賴就緒，依賴暫時不可達不代表服務本身壞了。

把 drain 窗口設成固定值不分 workload 類型，會在某一類服務上出事。5 秒對短 API 足夠、對長連線不夠、對 batch job 遠遠不夠。drain 窗口要依服務實際 workload 設定，不是用平台預設值。

把 liveness 失敗當成「服務壞了」而不問代價，會忽略重啟本身的連鎖效應。每次重啟都有在途請求中斷、連線重建、容量缺口的代價——特別是多實例同時被判定 liveness 失敗時，代價會被放大。

案例回寫

lifecycle contract 的完整性可用多個案例交叉驗證。5.C3 Orbitera managed K8s migration 揭露遷移後 readiness 依賴路徑改變的風險。5.C9 反例 揭露不同 workload 的 drain 條件被忽略造成的事故擴大。5.C7 Airbnb Istio 升級治理 揭露基礎平台元件升級缺乏分批治理會形成全域風險放大器。5.C10 對照 揭露不同規模下 lifecycle 驗證的缺口模式。

這些案例共同支撐的判讀是「lifecycle contract 的每個狀態都有不同的失敗模式，混在一起處理會在事故時無法定位」。流量切換或連線生命週期問題路由到 5.3 load balancer 合約。runtime 產物穩定性問題路由到 5.1 container 與 runtime。

跨模組路由

lifecycle contract 是部署模組的概念基底，後續章節都會引用本篇的狀態分類。

1. 與 5.1 的交接：runtime 與 entrypoint 定義 startup 行為回到 container 與 runtime。
2. 與 5.2 的交接：probe 設定與 rollout 節奏回到 Kubernetes 部署策略。
3. 與 5.3 的交接：drain 與流量退場回到 load balancer 合約。
4. 與 5.10 的交接：tunnel 入口的 readiness 與 drain 對齊回到 Outbound Tunnel 入口。
5. 與 4.20 的交接：lifecycle 事件的證據收集回到 Observability Evidence Package。
6. 與 6.8 的交接：lifecycle 狀態作為 release gate 判定條件回到 Release Gate。

下一步路由

要看 Kubernetes 如何承接這組生命週期，接著讀 5.2 Kubernetes 部署策略。要看流量退場如何和 LB 對齊，接著讀 5.3 load balancer 合約。要看不同平台的 lifecycle 表達力比較，接著讀 vendors/。

五個階段

早期開發

開發期的首要需求是 debug — 程式碼寫完跑起來、出問題時能定位。

開發期的取樣率全部設 1.0（全收）— 事件量極低（開發者自己操作），不需要取樣。

功能測試

針對被測功能開啟完整感測器，驗證功能的行為事件和效能指標是否正確觸發。

被測功能的 event 和 metric 全開。其他功能維持開發期設定。測試期間的感測器設定通常由測試 config 檔覆寫 SDK 預設值。

Production 上線

上線後的感測器組合平衡覆蓋率和成本：

A/B 測試

實驗感測器只對 treatment group 啟用。Control group 不觸發實驗事件，避免污染對照組資料。

實驗專用事件（experiment.pricing_test.assigned、experiment.pricing_test.converted）由 feature flag 控制 — flag 開啟時 SDK 才送這些事件。實驗結束後 flag 關閉，感測器自動停止。

實驗事件的保留期和實驗週期綁定，實驗結束 + 分析完成後可以 purge。

功能下線

功能移除時，對應的感測器 config 一起移除。Collector 端 purge 該功能的歷史事件（或降級到聚合摘要）。

移除 checklist：SDK config 移除事件名稱 → SDK 版本部署 → 確認 collector 不再收到該事件 → purge 歷史資料（可選）。

控制機制

三層控制機制各自適合不同的變更頻率：

SDK init config（靜態）

隨 app 版本部署的本地設定檔。變更需要發新版本。適合穩定的感測器組合。

 1sensors:
 2  error: { enabled: true, sampling: 1.0 }
 3  lifecycle: { enabled: true, sampling: 1.0 }
 4  event:
 5    funnel.*: { enabled: true, sampling: 1.0 }
 6    click.*: { enabled: true, sampling: 0.1 }
 7  metric:
 8    duration: { enabled: true, sampling: 0.5 }
 9  experiment:
10    pricing_test: { enabled: false }

Collector 端下發（動態）

SDK 啟動時從 collector 的 /config endpoint 拉取當前的感測器設定。Collector 端修改設定後，下一次 SDK 重啟或定期 refresh（每 5 分鐘）時生效。適合需要動態調整但不值得接 feature flag 服務的場景。

MVP 階段跳過 collector 下發，只用 SDK 本地 config。下發 API 的定義和實作標為第二階段 — 感測器的開關在 SDK 本地 config 已經能完全控制。

Feature flag 服務整合

SDK 在送出事件前查詢 feature flag 判斷感測器是否啟用。適合 A/B 測試 — flag 可以按使用者 / 百分比 / 條件分群啟用。

優先順序

三層控制的覆蓋優先順序：

1Feature flag > Collector 下發 > SDK 本地 config

SDK 本地 config 是 baseline。Collector 下發覆蓋 baseline 的特定欄位。Feature flag 覆蓋一切 — 即使本地 config 和 collector 都說啟用，flag 說關閉就關閉。

取樣率設計

取樣率決定「多少比例的事件會被實際送出」。取樣在 SDK 端執行 — 不送的事件不佔頻寬和儲存。

全收（sampling: 1.0）

每筆事件都送。適用於：

• error：每個 production error 都有 debug 價值，漏掉的 error 可能是最嚴重的那個
• 安全事件：auth 失敗、權限越界的取樣可能讓攻擊嘗試隱形
• 漏斗關鍵步驟：funnel 分析的轉換率計算需要精確的步驟計數

百分比取樣（0.01-0.5）

只送一定比例的事件。適用於高頻且個別事件價值低的場景：

• scroll / mousemove / hover：每秒觸發數十次，全收會產生大量事件。取樣 1-10% 足以分析使用者行為模式
• frame rate 量測：每幀一筆 metric 太多，每秒或每 30 秒取一筆足夠

取樣的實作用 SDK 端的隨機數 — if random() < sampling_rate then send(event) — 不需要 server 端參與。

條件取樣（retrospective full capture）

正常情況取樣，但發生 error 時回溯收集該 session 的全部事件。實作方式是 SDK 在記憶體中保留最近 N 筆事件的環形 buffer，觸發 error 時把 buffer 中的事件一併送出。

條件取樣讓「error session 的上下文完整」和「正常 session 不過度收集」兩個目標共存。

感測器開關的可觀察性

感測器本身的狀態變化需要被觀察 — 如果感測器靜默失效（config 錯誤導致某類事件停送），開發者可能很久後才發現「怎麼最近沒有 funnel 資料」。

啟動時 log 感測器清單

SDK 初始化完成時 log 當前啟用的感測器清單和取樣率。開發者在 debug console 就能看到「哪些感測器在跑」。

Config 變更事件

感測器 config 變更時（collector 下發新 config、或 feature flag 變化），SDK 送一個 lifecycle 事件：

1{
2  "type": "lifecycle",
3  "name": "sensor.config.changed",
4  "data": {
5    "source": "collector_push",
6    "changed": {"click.*": {"sampling": "0.1 → 0.05"}},
7    "active_sensors": 12
8  }
9}

這筆事件讓開發者在查詢時能看到「某個時間點感測器 config 改變了」，和事件量的變化做交叉比對。

下一步路由

• 感測器偵測哪些行為 → 前端感測器設計
• SDK 的公開 API → SDK 公開 API 設計
• 四類事件的定義 → 四類事件的完整定義
• 事件枚舉方法 → 事件枚舉與補齊檢查

本篇紀錄三個 dimension（RAM / 磁碟 / port）的觀察工具跟釋放姿勢、對比 Ollama 跟 ComfyUI 兩種典型 lifecycle、加上實測釋放數字。對應 0.7 隱私資料流原理「每個 hop 都要 audit」這條思維——資源管理也是 hop 級的 audit、不是「裝完就忘」。

驗證日期：2026-05-12 環境：macOS 14、Apple Silicon、Ollama 0.23.2、ComfyUI 0.21.0、SDXL base 1.0

為什麼這事重要

雲端 inference：

1Container start → load model → serve requests → container stop → 所有 RAM / 磁碟 / port 自動回收

本地 inference：

1brew services start → load model on demand → serve → ??? → 你忘記 stop
2                                              → RAM / 磁碟一直被佔
3                                              → 下次重開機才釋放

具體會踩到的問題：

• RAM：18 GB SDXL 模型載入後不會自動卸、即使 ComfyUI idle、Python process 仍占 RAM
• 磁碟：ollama pull 累積、~/.ollama/models/blobs 半年可長到 50 GB+、不主動清不會減
• Port：上次 crash 的 ollama serve 進程沒乾淨清、port 11434 還占著、下次啟動報「address already in use」
• GPU / Metal：模型載入後 Metal context 佔住、跟其他 GPU-using app（影片剪輯、遊戲）競爭

三個 dimension + 觀察工具

實測：剛 kill 完 ComfyUI（SDXL + Python venv）後、vm_stat 看到 free pages 從 619K 變 1090K（每 page 16 KB）、約 +7.5 GB RAM 釋放——這就是 SDXL + ComfyUI process 一直占的記憶體量。

Ollama 的 lifecycle（auto-unload 模式）

Ollama 走「按需 load / idle unload」設計：

1brew services start ollama          → daemon 啟動、沒 model 載入、RAM 占用 ~200 MB
2                                     port 11434 listening
3ollama run gemma3:4b "hello"        → 把 model 載入 RAM (~4-5 GB)
4                                     立刻 generate response
5                                     model 留在 RAM
6(idle 5 分鐘、無新 request)         → Ollama 自動 unload model
7                                     RAM 釋放、daemon 仍跑著
8ollama run gemma3:4b "next"         → 重新 load model（~5-10 秒）、generate
9brew services stop ollama           → daemon 結束、port 釋放

關鍵參數 OLLAMA_KEEP_ALIVE（環境變數、預設 5m）：

 1# 看當前 loaded models
 2ollama ps
 3# NAME         ID              SIZE      PROCESSOR    UNTIL
 4# gemma3:4b    a2af6cc3eb7f    5.5 GB    100% Metal   4 minutes from now
 5
 6# 啟動時調 keep_alive（持續佔 RAM 直到 ollama 重啟）
 7OLLAMA_KEEP_ALIVE=-1 brew services restart ollama
 8
 9# 啟動時讓 model 用完立即 unload
10OLLAMA_KEEP_ALIVE=0 brew services restart ollama

選 keep_alive 的 trade-off：

主動 unload 指令：

1# 把 idle 的 model 立刻從 RAM 卸掉、但 daemon 仍跑
2curl -s http://localhost:11434/api/generate \
3  -d '{"model": "gemma3:4b", "keep_alive": 0}'
4
5# 或關掉整個 daemon
6brew services stop ollama

ComfyUI 的 lifecycle（持續占用模式）

ComfyUI 走完全不同模式：model 載入後一直在 RAM、直到 server process 結束。沒有 auto-unload 機制。

 1python main.py                      → ComfyUI server start、port 8188 listening
 2                                     RAM ~3 GB（Python venv + 框架）
 3第一次 Queue Prompt (用 SDXL)        → 載入 sd_xl_base_1.0.safetensors (~6 GB)
 4                                     RAM 跳到 ~9-10 GB
 5                                     generate 完成、model 留在 RAM
 6連續多張生成                          → 維持 ~9-10 GB、沒 unload
 7idle 1 小時                          → 仍 ~9-10 GB（沒 timer）
 8切到 ControlNet workflow             → 多載 ControlNet model (~2 GB)、ComfyUI 自動 swap
 9                                     RAM 暫升、SD 部分可能被 evict 到 disk
10Ctrl+C / pkill                       → process 結束、RAM 完全釋放

要釋放 ComfyUI 占的 RAM、唯一方法是結束 server：

 1# 找 PID
 2ps aux | grep "ComfyUI/main.py" | grep -v grep
 3
 4# 優雅關（讓它 cleanup）
 5pkill -INT -f "ComfyUI/main.py"
 6
 7# 強制 kill（如果上面沒反應、最多等 5 秒再強制）
 8pkill -KILL -f "ComfyUI/main.py"
 9
10# 確認 port 釋放
11lsof -i :8188 | head -3

實測：M4 Pro 32GB、SDXL base 載入後 ComfyUI process 占 ~8 GB RAM；pkill -9 後 vm_stat 顯示 free pages 增加 ~470K page（7.5 GB 釋放）。

為什麼 Ollama 跟 ComfyUI 設計不同

兩種設計都 valid、適合不同使用模式。理解差異後就知道 ComfyUI 一直占 RAM「不是 bug」、是設計選擇。

跟其他本地 server 對比

結論：只有 Ollama 跟 oMLX 內建 auto-unload、其他都要手動釋放。GUI server（LM Studio）通常給 user 一個「Eject」按鈕、CLI server 通常要 kill process。

標準釋放程序

寫 code 完一天結束、要釋放所有資源、按下表順序操作：

 1# 1. 確認當前狀態（記下要還回去多少 RAM）
 2vm_stat | head -3
 3df -h ~ | tail -1
 4ollama ps
 5ps aux | grep -E "ollama|ComfyUI|llama-server" | grep -v grep
 6
 7# 2. 釋放當前載入的 LLM models（Ollama）
 8brew services stop ollama
 9# 或保留 daemon、只 unload model：
10# curl -s http://localhost:11434/api/generate -d '{"model": "<your model>", "keep_alive": 0}'
11
12# 3. 結束 ComfyUI / 其他 GUI server
13pkill -INT -f "ComfyUI/main.py" 2>/dev/null
14pkill -INT -f "llama-server" 2>/dev/null
15sleep 5
16# 強制（如果上面沒清乾淨）
17pkill -KILL -f "ComfyUI/main.py" 2>/dev/null
18pkill -KILL -f "llama-server" 2>/dev/null
19
20# 4. 驗證所有 port 釋放
21lsof -i :11434 -i :1234 -i :8080 -i :8188 -i :8000 2>&1 | head
22
23# 5. 確認釋放量
24vm_stat | head -3
25# free pages 該明顯增加

容易出錯的「釋放方式」

• killall Python：會 kill 所有 Python process、包括其他 dev tool（如 jupyter、Django）。用 pkill -f "ComfyUI/main.py" 等明確 pattern。
• rm -rf ~/.ollama：會清掉所有 model registry、下次要重 pull 全部 model。Cleanup 用 ollama rm <model> 才精準。
• brew uninstall ollama：直接卸載 Ollama 本身、過 reinstall 麻煩。Stop service 就夠。
• 重開機釋放：work 但太重、會中斷其他工作。用 process-level 操作即可。

磁碟長期累積管理

Models 一旦 pull 進 ~/.ollama/models/blobs、不主動 rm 不會減少。半年累積可長到 50 GB+。

Ollama models 只是磁碟大戶之一。整台 Mac 突然被吃光、要從哪裡查起的全機診斷順序（先排除快照浮動、再用實際佔用值逐層找大戶），見 macOS 磁碟空間診斷流程——那篇的佔用大戶表也會把 ollama 列為其中一項、再連回本篇的專屬清理 idiom。

觀察累積

 1# Ollama models 總占用
 2du -sh ~/.ollama/models/blobs
 3# 4.1G    /Users/tarragon/.ollama/models/blobs
 4
 5# 逐 model 看大小
 6ollama list
 7# NAME                       ID              SIZE      MODIFIED
 8# gemma4:e4b                 c6eb396dbd59    9.6 GB    Less than a second ago
 9# nomic-embed-text:latest    0a109f422b47    274 MB    3 hours ago
10
11# ComfyUI checkpoints 累積
12du -sh ~/.ollama ~/Projects/ComfyUI/models 2>/dev/null
13# 4.2G    /Users/tarragon/.ollama
14# 7.0G    /Users/tarragon/Projects/ComfyUI/models

清理策略

 1# 刪掉很久沒用的 model
 2ollama rm <model-tag>
 3
 4# 一次清掉所有 Ollama models（保留 daemon）
 5ollama list | tail -n +2 | awk '{print $1}' | xargs -I {} ollama rm {}
 6
 7# 看 ComfyUI checkpoints 哪些可清
 8ls -lh ~/Projects/ComfyUI/models/checkpoints/
 9
10# 手動刪不要的 .safetensors（小心、不能 undo）
11rm ~/Projects/ComfyUI/models/checkpoints/<old-model>.safetensors

磁碟管理 idiom

定期（每月或磁碟剩 < 20% 時）做：

1. du -sh ~/.ollama ~/Projects/ComfyUI/models 看當前累積
2. ollama list 看哪些 model 沒在用（看 MODIFIED 欄、太舊的考慮刪）
3. 刪實驗用的 model、保留 daily-driver
4. ComfyUI checkpoints 同樣 review

Port / Process 排錯

啟動報「address already in use」

 1# 找誰占
 2lsof -i :11434
 3# COMMAND  PID  USER   ...   NAME
 4# ollama   xxx  ...    ...   TCP localhost:11434 (LISTEN)
 5
 6# 看是不是 zombie process
 7ps aux | grep $(lsof -ti :11434 | head -1)
 8
 9# 清掉
10kill -9 $(lsof -ti :11434)
11
12# 或重啟 service（會自動清舊 instance）
13brew services restart ollama

Ollama daemon 掛了不知道

 1# 健康檢查
 2curl -s http://localhost:11434/api/version
 3
 4# 沒回應、看 service 狀態
 5brew services list | grep ollama
 6
 7# 沒在跑、重啟
 8brew services start ollama
 9
10# 看 log
11tail -50 /opt/homebrew/var/log/ollama.log

ComfyUI 看似跑著但 Queue 不動

1# 看 stdout / stderr log
2tail -30 /tmp/comfyui.log  # 如果啟動時 redirect 到 log
3
4# 看是不是 GPU / Metal stuck（極少見、但 SDXL 大量並發可能踩到）
5# 解法：kill + 重啟
6pkill -9 -f "ComfyUI/main.py"

完整排錯流程跟「先確認哪一層壞」見 1.7 排錯方法論。

觀察記憶體佔用：實測對照

跑這幾步紀錄 baseline → load model → kill 的 RAM 變化：

 1# Baseline
 2vm_stat | grep "Pages free"
 3# Pages free:                              1090076.   ← ~17 GB free
 4
 5# 啟動 Ollama + load 4B model
 6brew services start ollama
 7ollama run gemma3:4b "hello"
 8ollama ps
 9# NAME       SIZE     PROCESSOR    UNTIL
10# gemma3:4b  5.5 GB   100% Metal   4 minutes from now
11
12vm_stat | grep "Pages free"
13# Pages free:                               750000.   ← 跌 ~5 GB（model 載入）
14
15# 額外啟動 ComfyUI + load SDXL
16nohup python main.py > /tmp/comfyui.log 2>&1 &
17# 在 GUI 上 Queue Prompt 跑一次 SDXL generation
18vm_stat | grep "Pages free"
19# Pages free:                               280000.   ← 再跌 ~7.5 GB（SDXL 載入 + Python venv）
20
21# kill 全部
22brew services stop ollama
23pkill -9 -f "ComfyUI/main.py"
24sleep 3
25vm_stat | grep "Pages free"
26# Pages free:                              1090000.   ← 回到 baseline

每 page 16 KB、所以 free pages 數字 × 16 KB = 實際 free RAM bytes。

自動化釋放：launchd / shell alias

寫個 shell function 一鍵 cleanup：

 1# 加進 ~/.zshrc
 2llm-cleanup() {
 3  echo "[*] Stopping Ollama..."
 4  brew services stop ollama 2>/dev/null
 5
 6  echo "[*] Killing ComfyUI..."
 7  pkill -INT -f "ComfyUI/main.py" 2>/dev/null
 8  sleep 3
 9  pkill -KILL -f "ComfyUI/main.py" 2>/dev/null
10
11  echo "[*] Killing other model servers..."
12  pkill -KILL -f "llama-server" 2>/dev/null
13  pkill -KILL -f "lm-studio-server" 2>/dev/null
14
15  echo "[*] Verifying ports..."
16  for p in 11434 1234 8080 8188 8000; do
17    lsof -i :$p 2>/dev/null | head -2
18  done
19
20  echo "[*] Free RAM:"
21  vm_stat | grep "Pages free"
22}

完事打 llm-cleanup 一鍵釋放、不用記每個 process 怎麼 kill。

何時這篇會過時

不會過時的部分：

• RAM / 磁碟 / port 三個 dimension 是長期 invariant、用什麼 LLM server 都成立。
• 「Mac 是 shared resource、需要主動管理」這個 framing。
• Ollama 跟 ComfyUI 兩種典型 lifecycle 對比（auto-unload vs persistent）。
• 觀察工具（vm_stat、lsof、ps、du、Activity Monitor）是 macOS 系統 API、不會 deprecate。
• 標準釋放程序、自動化 shell function 模式。

會變的部分：

• 具體 model size / RAM 占用數字（隨模型架構演化）。
• OLLAMA_KEEP_ALIVE 等具體環境變數名（Ollama API 演化）。
• ComfyUI 可能加 auto-unload feature（社群有 issue 在討論）。

讀的時候若指令跑不過、先 --help 看當前版本 flag；釋放 RAM 的「kill process」這個機制本身永遠成立。

跟其他 hands-on 章節的關係

• Ollama 安裝：介紹 brew services start/stop、本篇延伸 lifecycle 細節
• ComfyUI 安裝：介紹 ComfyUI 啟動、本篇延伸 RAM 占用 + 釋放
• 1.7 排錯方法論：用三層架構定位故障、本篇是 lifecycle 視角的補完
• 0.7 隱私資料流原理：「每個 hop 都要 audit」延伸到資源層

整體心法：本地 LLM 工作流跟雲端不一樣、要主動管理 lifecycle、不能裝完就忘。

概念位置

Startup probe 位在 container 啟動與 readiness / liveness 之間。startup probe 成功前，liveness 和 readiness 不會啟動。startup probe 一旦成功就永久停用，由 liveness 和 readiness 接手。可先對照 Graceful Shutdown。

可觀察訊號

系統需要 startup probe 的訊號是「服務啟動時間超過 liveness 的預設容忍窗口」。典型場景：JVM 服務 warmup 需 30-60 秒、依賴多的服務需要等資料庫連線池和 cache 連線建立。沒有 startup probe 時，liveness 會在初始化期間把健康的服務判定為壞掉，觸發 restart loop。

設計責任

startup probe 的總容忍時間 = failureThreshold × periodSeconds。設計時先量測服務在最差情境下的啟動時間（冷啟動 + image pull + 依賴連線），再加 headroom。startup probe 跟 initialDelaySeconds 解決同一個問題，但 startup probe 在啟動期間持續探測（能偵測啟動失敗），initialDelaySeconds 是盲等（無法觀測啟動進度）。

核心論點

Detection engineering lifecycle 的核心概念是把規則當資產管理。規則資產包含來源、邏輯、測試、誤報處理、owner、驗收門檻與退場條件。

讀者入口

本篇適合銜接 7.B2 從偵測到回應的路由、7.13 偵測覆蓋率與訊號治理 與 Sigma：偵測規則生命週期素材。

生命周期欄位

生命周期欄位的核心是讓規則維護可以追溯。每次規則更新都能回查它解哪個風險、用哪個證據驗證、為何做這次調整。

規則來源治理

規則來源治理的責任是讓規則與威脅假設對齊。來源可來自公開框架、事件教訓、演練情境與稽核要求，並需要在建立時寫清楚 threat hypothesis 與 data dependency。

驗證節奏

驗證節奏的責任是確保規則在上線前後都保持有效。建議至少建立三層驗證：

1. 邏輯驗證：條件可讀、可測、可重現。
2. 資料驗證：log schema 與欄位品質可支撐判讀。
3. 情境驗證：在事件回放或 game day 中能命中目標行為。

調校策略

調校策略的責任是把 alert 噪音轉成可判讀訊號。調校時同步記錄 false positive 情境、排除條件、影響範圍與回退方式，並和 incident severity 對齊分級節奏。

上線與退場

上線與退場的責任是讓規則變更進入受控流程。上線前需確認 evidence、owner 與回退路徑；退場時要確認替代規則、覆蓋遷移與歷史證據保留。

與事故流程的交接

與事故流程交接的責任是把規則命中轉成回應路由。規則命中後應直接輸出 triage 問題、owner、升級條件與 runbook 路由，讓 08 模組可以快速接手。

判讀訊號與路由

判讀表格的作用是把規則問題轉成維護任務。每一列都能直接對應到 owner 與下一步交接章節。

必連章節

• 7.B2 從偵測到回應的路由
• 7.B3 資安控制驗證
• 7.13 偵測覆蓋率與訊號治理
• 7.BM1 藍隊專業來源卡

完稿判準

完稿時要讓讀者能為一條偵測規則設計完整生命週期。輸出至少包含來源、邏輯、驗證證據、調校策略、上線條件、退場條件與回寫位置。