Graceful shutdown

Go 程式收到 SIGTERM 或 SIGINT 時需要在退出前完成清理：flush 剩餘的 buffer、關閉網路連線、寫入最後的 lifecycle 事件。

1ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGTERM, syscall.SIGINT)
2defer stop()
3
4<-ctx.Done()
5// signal received, start graceful shutdown
6monitor.Close(context.WithTimeout(context.Background(), 5*time.Second))

graceful shutdown 的時間窗口由部署環境決定。Kubernetes 的預設 terminationGracePeriodSeconds 是 30 秒，Docker 的 stop timeout 是 10 秒。SDK 的 Close 方法接受 context 讓呼叫端控制超時。

HTTP server 的 shutdown 順序

如果 Go 程式同時是 HTTP server 和 monitoring SDK 的使用者，shutdown 順序需要正確：

1. 停止接受新連線（server.Shutdown(ctx)）
2. 等待進行中的請求完成
3. flush 監控 buffer（monitor.Close(ctx)）
4. 關閉 log 和其他資源

如果先 close monitor 再 shutdown server，進行中的請求產生的事件會在 monitor 已關閉後嘗試送出，被靜默丟棄。

Signal handling

Go 的 signal.Notify 和 signal.NotifyContext 是接收 OS signal 的標準方式。SDK 在 init 時不應該自己註冊 signal handler — 這會和應用程式的 signal handling 衝突（Go 的 signal handler 是先到先得，後註冊的覆蓋先註冊的）。

SDK 端的適配方式是提供 Close 方法讓應用程式在自己的 signal handler 中呼叫，而非 SDK 內部攔截 signal。應用程式控制 shutdown 流程，SDK 只負責在被告知關閉時 flush 和清理。

panic recovery

Go 的 panic 會終止當前 goroutine。如果 panic 發生在 main goroutine 且沒有 recover，程式直接退出，SDK 的 buffer 中的事件遺失。

SDK 可以提供 monitor.RecoverAndReport() 讓開發者在 goroutine 的入口用 defer monitor.RecoverAndReport() 攔截 panic，記錄 error 事件後再 re-panic（保持原有的 crash 行為）。

HTTP handler 的 panic 可以用 middleware 攔截：

1func monitorMiddleware(next http.Handler) http.Handler {
2    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
3        defer monitor.RecoverAndReport()
4        next.ServeHTTP(w, r)
5    })
6}

HTTP server 自身監控

Go 常用來寫 collector 本身。Collector 需要監控自己的健康狀態 — 請求處理速率、錯誤率、goroutine 數量、記憶體使用量。

Collector 的自身監控和接收外部事件是兩個獨立的管線。自身監控的 metric 可以寫入獨立的 JSONL 檔案（和外部事件分開），或透過 Go 的 expvar / runtime.ReadMemStats 暴露為 HTTP endpoint。

自身監控的關鍵指標：

• collector.events.received：每秒收到的事件數
• collector.events.invalid：schema 驗證失敗的事件數
• collector.storage.write_duration_ms：寫入 JSONL 的耗時
• collector.goroutines：goroutine 數量（洩漏偵測）
• collector.memory.alloc_mb：記憶體使用量

下一步路由

• 跨平台 timestamp 一致性 → 跨平台 timestamp 一致性
• Collector 的架構設計 → 模組四 Collector 設計
• SDK 公開 API 的 Close 方法 → 模組三 SDK 公開 API

公開 customer engineering case 的累積量、是 vendor 社群活躍度跟長期可維護性的信號。case 多寡跟 vendor 工程能力沒有線性關係、跟以下因素相關：

• 社群活躍度（用戶數 + 用戶寫 blog 文化）
• Vendor 自身的 customer success / DevRel 投入
• Feature 成熟度（新 feature 公開 case 通常稀薄）
• 議題公開度（內部運維議題公司不常寫、incident / migration 容易寫）

選型時、公開 case 量值得作為信號之一、但要跟「該 vendor 是否仍積極開發」「文檔品質」「社群 issue 回應速度」等其他信號合併判讀。

為什麼

backend/03-message-queue 模組 6 vendor 案例採集發現 case 累積量差異極大：

差異不只是「採集力度」、是公開資料密度本身差異。

反模式

選型時誤用案例量的方式：

修法

選型時把案例量當合併信號之一、跟以下信號交叉判讀：

1. 議題對齊度：該 vendor 的 case 是否覆蓋你的需求形狀（吞吐 / 延遲 / 持久化 / 多租戶 / 跨區）？
2. Vendor 活躍度：GitHub release 節奏、issue 回應速度、CVE 修復時間
3. 生態整合：是否有你需要的 client library / framework / observability 工具
4. 社群健康：Stack Overflow 問題回答率、Discord / Slack 活躍度
5. 長期承諾：vendor 公司 / 基金會背景、license 模式、商業化路徑

單看案例量會誤導、但完全忽略也會錯失重要信號：某些 vendor 案例量低反映社群活躍度低、選型後遇到問題找不到參考、自己要從零摸索。

關係

• 跟採集流程的關係：採集到「該 vendor 公開 case 偏少」是真實信號、不是採集失敗、不該強求 10 個案例
• 跟 case-driven 寫作的關係：公開 case 稀薄的章節改走 standard-driven 或通用工程知識補強、明示覆蓋缺口
• 跟 vendor 選型的關係：案例量是合併信號之一、不是主要判讀依據

case

backend/03-message-queue 模組採集後盤點：

• Kafka 17+ 案例、議題覆蓋廣度高、但 KRaft / 部分新 feature 仍稀薄
• NATS 8 案例、議題集中在 IoT / edge / multi-cloud、其他場景偏少
• Redis Streams 6 案例、Stream + Functions / Cluster on Streams 缺、是 feature 成熟度信號
• Pub/Sub Mercari 4 篇深度 case 是 anchor cluster、品質高過案例量

選型時把這些差異當輔助信號、不當主判讀。

判讀徵兆

何時案例量該升為主要選型信號：

• 該領域有很多 vendor 都做類似功能（如 message broker 有 7+ 個 vendor）、案例量可以區分活躍度
• 該 vendor 是新興 / 商業化不確定（vendor lock-in 風險）、需要評估社群獨立性
• 該 vendor 過去有 license 改變或商業化轉向（Redis / Elasticsearch / MongoDB）、社群 fork 的活躍度該追蹤

何時案例量不該當主要信號：

• 需求形狀已有明確 vendor 對齊（如 GCP 生態下 Pub/Sub 是預設）
• Vendor 公司本身極穩定（AWS / Google managed service）
• 主要 case 集中在反例 / 退場案例（這時案例多反而是負面信號）