五段處理鏈路

第一段：HTTP endpoint 接收

Collector 對外提供一個 HTTP POST endpoint（例如 /v1/events），接收 SDK 送來的 JSON body。每個 request 可以是單一事件或批次事件陣列。

Endpoint 的職責只有兩件事：驗證 HTTP 層面的基本條件（Content-Type、body size limit、認證 token），然後把 body 傳給下一段。HTTP 層面的錯誤（413 body too large、401 unauthorized）在這裡回應，不進入後續處理。

自用工具場景下，Go 的 net/http 標準庫提供的 HTTP server 已足夠。一個 http.HandleFunc("/v1/events", handler) 加上 json.NewDecoder(r.Body).Decode(&events) 就完成接收。不需要 framework。

第二段：JSON Schema 驗證

收到的 JSON body 用 JSON Schema 驗證結構正確性 — 必要欄位是否存在、型別是否正確、值是否在合法範圍內。驗證失敗的事件被拒絕並記錄原因，通過的事件進入下一段。

Schema 驗證是 collector 的品質閘門。沒有驗證的 collector 會累積格式不一致的資料，查詢時需要處理各種邊界條件。驗證在寫入前攔截問題，比寫入後清理成本低。

驗證的粒度是事件級 — 批次中的一個事件驗證失敗不影響其他事件。回應中標明哪些事件被接受、哪些被拒絕及原因。

Ingestion 回應格式

回應格式把「接受了幾筆、拒絕了幾筆、拒絕原因」三件事用一套一致的結構表達。SDK 端只需要判斷 status code 就知道怎麼處理 buffer。

 1// 200 OK — 單筆成功或批次全部成功
 2{ "accepted": 1 }
 3
 4// 207 Multi-Status — 批次部分失敗
 5{
 6  "accepted": 1,
 7  "rejected": 1,
 8  "errors": [
 9    { "index": 1, "message": "missing required field: type", "fields": ["type"] }
10  ]
11}
12
13// 400 Bad Request — 單筆失敗或批次全部失敗
14{
15  "error": "schema validation failed",
16  "details": [
17    { "field": "type", "message": "missing required field" }
18  ]
19}
20
21// 503 Service Unavailable — 寫入端暫時不可用
22{ "error": "service temporarily unavailable", "retry_after": 5 }

設計選擇：207 的 errors 陣列用 index 標明失敗事件在原始 batch 中的位置（0-based），SDK 可以用 index 對照原始事件做 debug log。合法事件不因部分失敗而被丟棄 — 部分成功是 batch 收集的核心價值。400 和 207 的差異是「全軍覆沒 vs 部分存活」，SDK 端的處理策略不同：400 直接清 buffer（schema 問題重試也不會過），207 只清成功的部分。

Health endpoint 回應

Health endpoint 回傳 collector 自身的運行狀態，不包含事件內容。用途是 SDK 端確認 collector 可達、監控腳本定期探測。

1// GET /health → 200 OK
2{
3  "status": "ok",
4  "uptime_seconds": 3600,
5  "total_events": 1234,
6  "storage_bytes": 5242880,
7  "version": "0.1.0"
8}

total_events 和 storage_bytes 讓監控腳本判斷 collector 的負載趨勢。version 讓 SDK 確認 collector 版本（schema 不匹配時的第一個 debug 線索）。

第三段：儲存

通過驗證的事件寫入 Storage Backend。Collector 使用可插拔的 Storage interface — day-one 預設用 SQLite（零依賴、嵌入式），分析需求觸發時切換到 PostgreSQL。具體的 backend 選擇和功能分層見 功能分層與 Backend 選擇，可插拔架構見 規模演進。

第四段：查詢

儲存的事件透過 CLI 指令或 HTTP 查詢 endpoint 存取。SQLite backend 下用 SQL 查詢；匯出為 JSONL 格式後也可用 grep + jq 做臨時分析。

查詢設計見 查詢 API 設計。

第五段：Rule engine

Rule engine 在事件寫入後觸發，檢查事件是否匹配預定義的規則。匹配時執行對應的動作（發通知、寫 summary、觸發 webhook）。

Rule engine 設計見 Rule engine 設計。

多獨立 client 併發寫入

上述五段鏈路描述的是單一 request 的路徑。實際運行時，多個 SDK 會同時送事件——以下先描述場景，下方並發寫入策略再詳述 collector 如何處理。

常見部署場景中，多個完全獨立的 SDK 實例同時送事件到同一個 collector——不同 process、不同 app、甚至不同語言的 SDK。這和「一個 app 內的多 thread 併發」不同：每個 SDK 有自己的 buffer 和 HTTP 連線，不共享任何狀態。

SDK 端不需要知道其他 SDK 的存在。每個 SDK 獨立 init、獨立 buffer、獨立 flush、獨立 close。SDK 端的唯一接觸點是 collector 的 HTTP endpoint——併發安全由 storage backend 的併發策略保證（見下方並發寫入策略），不需要 SDK 端協調。多 client 同時 flush 時的背壓機制見 Ingestion 背壓與流量管控。

例如 CI pipeline 的多個 job 同時送 build 事件，或微服務架構中多個 service 各自送事件到同一個 collector。另一個具體案例是 Claude Code 的 Hook 系統——多個 Hook 同時觸發時，每個 Hook 是獨立的 Python process，各自初始化 SDK、產生事件、flush 到同一個 collector。

並發寫入策略

Go 的 HTTP server 為每個 request 分配一個 goroutine。多個 SDK 同時 flush 時，collector 同時收到多個寫入請求。Storage Backend 的並發能力決定了這些 goroutine 怎麼協調。

SQLite Backend：單寫者模型

SQLite 的 WAL mode 允許一個 writer 和多個 concurrent reader — 讀寫不互相阻塞，但多個 writer 之間是序列化的。Go 端有兩種處理 pattern：

Single-writer goroutine + channel：所有 Store() 呼叫把事件送進一個 Go channel，由一個專屬的 goroutine 從 channel 讀取並序列寫入 SQLite。HTTP handler 送完 channel 後等待確認（或用 buffered channel 異步）。優點是背壓控制清晰 — channel 滿時 HTTP handler 自然阻塞，可以回 503。缺點是多一層間接。

Busy timeout fallback：不在 Go 層管序列化，讓 SQLite driver 自己處理。設定 _pragma=busy_timeout(5000)，多個 goroutine 同時呼叫 Store() 時，SQLite 讓等待的 goroutine block 直到寫入鎖釋放（最多 5 秒）。優點是實作簡單（不需要 channel 和額外 goroutine）。缺點是背壓不可控 — goroutine 數量可能累積。

自用工具場景推薦 busy timeout（簡單）、寫入量增長到出現超時錯誤時切換到 channel pattern。

PostgreSQL Backend：連線池

PostgreSQL 透過連線池（database/sql 的 SetMaxOpenConns）支援並行寫入。多個 goroutine 可以同時寫入不同的連線，不需要額外的序列化機制。

Go 單一 binary 的設計選擇

Collector 用 Go 編譯成單一 binary，不依賴外部 runtime（JVM、Python interpreter、Node.js）。部署是複製一個檔案，啟動是執行一個指令。

這個選擇在自用工具場景下有特定優勢：server 和 collector 在同一台機器上，部署流程是 scp collector user@host: + ssh user@host ./collector。不需要 package manager、不需要 container registry、不需要 orchestration。

Go 的 net/http 標準庫提供 production-ready 的 HTTP server，JSON 處理用標準庫的 encoding/json，SQLite 用 modernc.org/sqlite（pure Go、無 CGO 依賴）。整個 collector 的核心邏輯可以在 500 行以內完成。

具體的部署步驟（systemd service 檔案、啟動參數、設定檔格式）和 Quick Start（從零到第一筆事件出現在 collector）見 monitor repo 的 deployment guide。

下一步路由

• 功能分層與 Backend 選擇 → 功能分層與 Backend 選擇
• 可插拔 Storage Backend 架構 → 規模演進
• JSONL 匯出與備份格式 → JSONL 儲存設計
• 查詢 API 的設計 → 查詢 API 設計
• Rule engine → Rule engine 設計
• 背壓與流量管控的基礎概念 → DevOps 流量管控
• 端到端資料完整性 → 端到端資料完整性
• Error fingerprint 與去重分群 → Error Fingerprint 與去重分群

概念位置

CI Pipeline 位在開發提交、pull request 與主線保護之間，常由 lint、test、build、security check 組成。

可觀察訊號

• PR 需要依賴檢查結果決定能否合併。
• 團隊需要一致的失敗判讀入口。
• 本機通過但共享流程失敗時，需要明確定位差異。

接近真實服務的例子

前端專案會把 markdown lint、browser test 與 production build 放在同一套 CI 驗證入口。後端專案則可能加入 contract test、migration check 或 image scan。

設計責任

CI Pipeline 要定義必跑檢查、失敗回饋路由與執行時間上限，讓綠燈具備可發布前提。

概念位置

CD Pipeline 位在 CI 驗證之後，負責 artifact promotion、部署執行、環境保護與回復路徑。

可觀察訊號

• 同一份 artifact 需要在多個環境推進。
• 發布步驟需要審核、權限或時間窗控制。
• 發布失敗時需要可回退或可修復路徑。

接近真實服務的例子

靜態站會在 CI 成功後上傳 artifact 到 hosting。後端服務會推進同一個 image tag 到 staging 與 production，並以 rollout strategy 控制風險。

設計責任

CD Pipeline 要明確定義放行條件、部署順序、例外流程與回復策略，確保發布節奏與風險控制一致。

本文是 Redis overview 的 implementation-layer deep article。連線與往返是 application 端量到的延遲主因，跟 server 端的記憶體、持久化調校互補。pipeline 機制以 Redis pipelining 官方文件 為準、最後檢查日 2026-06-16。

延遲不在 Redis、在往返

把單一 GET 丟進 redis-cli --latency，會看到 server 端執行時間是微秒級。但 application 端的 APM 量到的 Redis 呼叫卻是 1-3ms。這個差距不是 Redis 變慢了，是網路往返（round-trip time，RTT）——命令從 application 送到 Redis、結果送回來，這趟來回就是毫秒級，而 Redis 的執行只佔其中一小部分。

這個認知翻轉了 Redis 優化的方向：當你的服務每個請求要打 10 個 Redis 命令，瓶頸不是 Redis 的吞吐，是 10 次 RTT 疊加成 10-30ms。pipelining 常被講成「批次發命令省效能」，但它真正消除的是 RTT 稅——把 10 次往返打包成 1 次往返，server 端執行時間幾乎不變，但 application 端延遲從 10×RTT 降到 1×RTT。

對每次互動要查多個 cache 的服務，這筆 RTT 稅是延遲預算的主要支出。Snap 在 multi-cloud 架構下的痛點正是這個放大版：application 在一個 cloud、cache 在另一個，每次 lookup 多吃 5-30ms 跨 cloud RTT，「5ms × 10 cache lookup = 50ms 額外延遲」。Snap 把 KeyDB 部署到同 cloud 減少跨 cloud RTT，本質就是降低往返稅。本文處理 RTT 的會計、連線池配置與 pipeline 的正確使用。

核心概念：RTT 會計與三種降稅手段

Redis 一次請求的延遲拆成三段：client 序列化 + 送出、網路往返（RTT）、server 執行。多數 cache 場景下 RTT 是主導項，server 執行可忽略。降低總延遲有三種手段，對應三種「省 RTT」的方式：

連線池消除「每次都建連線」的稅。建立 TCP 連線（三次握手）本身就是一趟 RTT，若還有 TLS 再加幾趟。每個請求都新建連線等於每次都付建連稅。連線池讓連線重用，把建連成本攤平到接近零。

pipelining 把 N 次 RTT 壓成 1 次。連續送 N 個命令而不等每個的回應，一次讀回 N 個結果。這要求這 N 個命令彼此無依賴（後一個不需要前一個的結果）。

Lua script / 多 key 命令把多操作合成 1 次往返且原子。當命令之間有依賴（讀了再決定怎麼寫），pipeline 不適用（後面的命令送出時前面的結果還沒回來），這時用 Lua script 把邏輯放到 server 端一次執行，省 RTT 又拿到原子性。

pipeline 跟 MULTI 是不同的東西

這兩個常被混淆，但解的問題不同：

pipeline 純粹是傳輸層優化，不保證原子性——pipeline 裡的命令在 server 端仍可能跟其他 client 的命令交錯。要原子性用 MULTI/EXEC 或 Lua。兩者也可以組合（在 pipeline 裡送 MULTI…EXEC）。

注意 Redis 的 MULTI/EXEC 不是關聯式 DB 的 transaction：執行期某命令出錯（例如對 string 做 list 操作）不會回滾已執行的命令，它沒有 rollback。

配置：連線池與 pipeline 的設定路徑

連線池配置（以 Python redis-py 為例，多數 client library 概念一致）：

 1import redis
 2
 3pool = redis.ConnectionPool(
 4    host="10.0.0.1", port=6379,
 5    max_connections=50,          # 池上限、依並發量與 Redis maxclients 反推
 6    socket_timeout=0.5,          # 單命令逾時（秒）——必設、否則慢命令拖垮 caller
 7    socket_connect_timeout=0.5,  # 建連逾時
 8    health_check_interval=30,    # 定期檢查連線存活、清掉壞連線
 9)
10r = redis.Redis(connection_pool=pool)

socket_timeout 是最常被遺漏卻最關鍵的設定——沒設逾時，一個慢命令或網路黑洞會讓 caller 無限等待，連鎖拖垮上游。

pipeline 的使用：

1# pipeline：N 個無依賴命令、一次往返
2pipe = r.pipeline(transaction=False)  # transaction=False 純 pipeline、不包 MULTI
3for uid in user_ids:                  # 假設要拿 100 個 user 的 profile
4    pipe.hgetall(f"user:{uid}")
5results = pipe.execute()              # 一次往返拿回 100 個結果

依賴型操作改用 Lua（命令間有讀後寫的依賴，pipeline 不適用）：

 1# 原子的 check-and-set：讀目前值、符合條件才更新——一次往返且原子
 2lua = """
 3local current = redis.call('GET', KEYS[1])
 4if current == ARGV[1] then
 5  redis.call('SET', KEYS[1], ARGV[2])
 6  return 1
 7end
 8return 0
 9"""
10cas = r.register_script(lua)
11cas(keys=["lock:resource"], args=["old_token", "new_token"])

MGET / MSET / HMGET 等原生多 key 命令是最簡單的省 RTT 手段——能用多 key 命令就不用 pipeline，更省事且原子。

Production 故障演練

Case 1：每請求新建連線、延遲全是建連稅

徵兆：Redis 呼叫延遲偏高且不穩，INFO stats 的 total_connections_received 速率極高（接近 QPS），Redis 的 connected_clients 反覆上下震盪。

根因：application 沒用連線池，或每個請求 redis.Redis(...) 重新建立 client。每次請求付一趟 TCP 握手（加 TLS 更多）的 RTT，建連稅疊在每個請求上。

修法：

1. 用連線池並重用，client 物件在 application 生命週期內共用，不是每請求建立
2. 短生命週期環境（Lambda / serverless）把連線池放在 handler 外（容器重用時連線存活）
3. 監控 total_connections_received 速率，遠高於合理重連頻率代表沒重用
4. TLS 場景的建連稅更高，連線重用的收益更大

Case 2：沒設 socket_timeout、一個慢命令拖垮整條鏈

徵兆：某次 Redis 短暫卡頓（fork 尖峰、網路抖動），application 端大量請求 hang 住不回，thread / connection 被耗盡，影響擴散到跟 Redis 無關的請求。

根因：連線沒設 socket_timeout。Redis 一旦慢回應或網路黑洞，caller 無限等待，佔住 thread 與連線，連鎖拖垮整個服務。

修法：

1. 一律設 socket_timeout（cache 場景通常幾百 ms 就該逾時，cache 本來就該快）
2. 逾時後 application 要有 fallback（回源或降級），不是把逾時當 fatal
3. 連線池 max_connections 設上限，避免無限建連把 Redis 的 maxclients 打滿
4. fork 尖峰是常見的慢源頭，對應 persistence deep article 的延遲尖峰治理

Case 3：一個巨大 pipeline 把 server 跟 client 都撐爆

徵兆：用 pipeline 批次處理時，某次塞了幾十萬個命令進一個 pipeline，Redis 記憶體尖峰、client 端記憶體爆，甚至 OOM。

根因：pipeline 把所有命令的 request 跟 response 都 buffer 起來。一次塞太多，server 端要 buffer 全部 reply（計入 used_memory、見 記憶體調校 的 output buffer），client 端要 hold 全部結果，雙邊記憶體尖峰。

修法：

1. pipeline 分批（chunk），每批幾百到幾千命令，不要一個 pipeline 塞無上限
2. 大量資料的掃描用 SCAN 游標分批，不要 KEYS * 一次撈
3. 監控 client output buffer（CLIENT LIST 的 omem），異常大代表有巨型 pipeline 或慢 consumer
4. 批次大小靠 RTT 與記憶體權衡——批次越大省越多 RTT，但記憶體尖峰越高

Case 4：在 cluster 模式對跨 slot key 開 pipeline / transaction 失敗

徵兆：單機 Redis 上運作正常的 pipeline 或 MULTI，搬到 Redis Cluster 後報 CROSSSLOT Keys in request don't hash to the same slot。

根因：Cluster 模式下 MULTI/EXEC 與某些多 key 命令要求所有 key 在同一個 hash slot。pipeline 在 cluster 下也要按 slot 分組送到對應 node——若 client library 不自動處理跨 slot，會失敗。

修法：

1. 同組操作的 key 用 hash tag {...} 強制同 slot（例如 user:{123}:profile、user:{123}:settings）
2. 用支援 cluster pipeline 的 client library，它會自動按 slot 分組
3. 設計階段就考慮 key 的 slot 分布，避免事後重構，對應 cluster re-sharding 的 hash tag 治理
4. 跨 slot 的批次邏輯改用 application 端聚合，不依賴 server 端原子性

Case 5：把 pipeline 當 transaction 用、出現資料競態

徵兆：用 pipeline 做「讀一個值、根據它決定寫什麼」的邏輯，高並發下偶發資料不一致——兩個 client 讀到同樣的舊值、各自寫入，一方覆蓋另一方。

根因：把 pipeline 誤當原子操作。pipeline 只是把命令打包傳輸，命令之間 server 端仍可能插入其他 client 的命令——它沒有原子性。讀後寫的依賴邏輯放 pipeline 裡，等於沒有任何併發保護。

修法：

1. 讀後寫的依賴邏輯用 Lua script（server 端原子執行），不用 pipeline
2. 樂觀鎖場景用 WATCH + MULTI/EXEC（watch 的 key 被改則 EXEC 失敗、重試）
3. 分清楚需求：要省 RTT 用 pipeline，要原子性用 Lua / MULTI，兩者目的不同
4. distributed lock 場景見 2.5 distributed lock，Redis 的鎖有自己的正確性陷阱

Capacity / cost 邊界

連線與往返的容量判讀，圍繞連線數與每請求往返次數：

撞牆後的路由判斷：

• 單執行緒 CPU 打滿、命令吞吐到頂：Redis 主執行緒單線處理命令，pipeline 省 RTT 但不增加 server 端平行度。CPU 到頂走 Cluster 分片把命令分散到多 node。
• 想要單機多核平行處理命令：DragonflyDB 的 shared-nothing 多核架構讓命令在單機就能多核平行，Redis 要靠 cluster 才能達到的吞吐它單機就能撐——高吞吐單機 workload 的替代。
• 跨 cloud / 跨 region 的 RTT 是結構性瓶頸：Snap 的解法是把 cache 部署到跟 application 同 cloud / 同 region，從根本消除跨區 RTT——這是架構層決策，不是 pipeline 能補的。

整合 / 下一步

連線與往返是 application 端延遲的主因，但它跟 server 端調校互補：

• 跟 記憶體調校：巨型 pipeline 的 server 端 reply buffer 計入 used_memory、慢 consumer 的 output buffer 是記憶體洩漏源頭。
• 跟 persistence / fork latency：fork 尖峰是 socket_timeout 必須存在的理由之一——慢源頭不只網路。
• 跟 Cluster re-sharding：cluster 模式改變 pipeline / transaction 的 key 分布規則，hash tag 治理是前提。
• 跟 2.6 high concurrency：高並發下的連線數爆炸與熱 key 是同一組壓力的不同面向，連線池上限與 local cache 兩層都是解法。

相關連結

• 上游 vendor 頁：Redis
• 同 vendor deep article：記憶體與淘汰調校、persistence 與 fork latency、Sentinel 與 failover 時序、Cluster re-sharding
• 上游概念：2.6 high concurrency、2.5 distributed lock
• Methodology：Vendor 深度技術文章寫作方法論