兩個粒度

Per-client（每來源限速）

限制每個 client（by API key / IP / SDK instance）的請求速率。防止單一來源打爆系統。

自用場景下 per-client 限速的價值不高（只有自己的 SDK），但開源工具被多人部署後，per-client 限速防止某個失控的 SDK 影響其他來源。

Global（全局限速）

限制系統的總吞吐量。不管多少個 client，collector 每秒最多處理 N 個事件。

Global 限速是系統保護的最後一道線 — 即使每個 client 都在限速內，所有 client 加起來可能超過系統承載。Global 限速確保總量不超過系統能力。

演算法

Token Bucket

桶裡有固定數量的 token，每個請求消耗一個 token，token 按固定速率補充。桶空了就拒絕。

特點：允許短暫 burst（桶滿時一次消耗多個 token），但長期平均不超過補充速率。適合「允許偶爾的高峰但長期平均要在限制內」的場景。

Sliding Window

在固定的時間窗口（如 1 分鐘）內計數請求。超過上限就拒絕。窗口結束時計數重設。

特點：嚴格的速率限制（窗口內不會超過 N 個），但窗口邊界有突增風險（上一個窗口末尾 + 下一個窗口開頭各 N 個 = 瞬間 2N）。滑動窗口（sliding window log / counter）解決邊界問題但記憶體較高。

選擇

自架監控系統推薦 token bucket — 允許 SDK 的 flush burst（一次送 100 個事件是正常行為），但限制長期平均速率。

HTTP 429 + Retry-After

限速觸發時回 HTTP 429 Too Many Requests，帶 Retry-After header 和 rate limit 相關 header：

1HTTP/1.1 429 Too Many Requests
2Retry-After: 5
3X-RateLimit-Limit: 1000
4X-RateLimit-Remaining: 0
5X-RateLimit-Reset: 1719302400

SDK 收到 429 後觸發離線 buffer 暫存事件，Retry-After 秒後重試。

優先級豁免

某些請求不應被限速：

優先級的判斷依據是「這個事件丟了的代價」。Error 事件丟了影響 debug 能力，event 事件丟了影響行為分析精度 — 前者的代價更高。

下一步路由

• 被動的流量控制 → 背壓機制
• 依賴失敗時的快速失敗 → 熔斷器
• 不同工作負載的資源隔離 → Bulkhead 隔離
• Backend 的 rate limit 實作（middleware / Redis / 配額設計）→ Rate Limit 實作

待寫章節

• 背壓機制（下游慢時上游怎麼減速）
• Rate Limiting（主動限制每個來源的請求速率）
• 熔斷器（依賴服務失敗時怎麼快速失敗而非拖慢自己）
• Bulkhead 隔離（不同工作負載的資源池隔離）

跨分類引用

• → monitoring 模組四 Collector：Collector 的 ingestion 防護是本模組的應用場景
• → devops 模組七 突發流量：突發流量時這四種機制怎麼組合使用
• → backend 可靠性：熔斷和 bulkhead 也是 backend 的可靠性設計元件

四層防線

每一層在不同規模觸發，由近到遠依序啟用。前一層能擋住的流量不需要啟用後一層。本章的四層按防線位置劃分（SDK / Collector / 基礎設施兩層）。DevOps 的規模分級應對表按 events/sec 量級劃分（Tier 1-4），兩者視角不同但覆蓋相同的擴展路徑。

第一層：SDK 端的流量控制

流量控制的最有效位置是事件產生的源頭。SDK 端減少的事件量，後面每一層都不需要處理。

動態取樣

SDK 在收到 collector 的 HTTP 429（Too Many Requests）回應時，自動降低取樣率。恢復正常後逐步回升。

1正常 → sampling 1.0
2收到 429 → sampling 降到 0.5
3持續 429 → sampling 降到 0.1
4連續 10 次成功 → sampling 回升到 0.5
5連續 30 次成功 → sampling 回到 1.0

動態取樣的控制邏輯在 SDK 端實作，不需要 collector 端額外支援 — 429 回應碼就是觸發訊號。和感測器生命週期管理的靜態取樣率互補 — 靜態取樣在 config 中設定、動態取樣在執行期自動調整。

聚合前移

SDK 端累積一段時間的同名事件，送出摘要而非逐筆。適合 metric 類的高頻取樣。

例：原本每 100ms 送一筆 render.frame_drop，改成每 5 秒送一筆 render.frame_drop_summary（帶 count + min + max + avg）。事件數從 50 筆/5s 降到 1 筆/5s。

聚合前移犧牲事件粒度換取吞吐量。只適合「趨勢比每筆細節重要」的 metric 類事件。Error 和 lifecycle 事件不做聚合 — 每筆的 stack trace 和狀態轉換都有 debug 價值。

優先級丟棄

SDK 的離線 buffer 滿時，按優先級丟棄。Error 的 debug 價值最高，最後丟。

第二層：Collector 單機的防護

Collector 在自身能力範圍內保護自己不被壓垮。和 architecture.md 的並發寫入策略直接相關 — 寫入 channel 是背壓的實作基礎。背壓和流量管控的通用概念見 DevOps 流量管控。

寫入 channel 容量 + 背壓

Single-writer goroutine pattern 的 Go channel 有固定容量（如 10,000）。Channel 滿時 HTTP handler 無法送入事件，此時回 429：

1select {
2case writeCh <- event:
3    w.WriteHeader(http.StatusAccepted) // 202
4default:
5    w.Header().Set("Retry-After", "5")
6    w.WriteHeader(http.StatusTooManyRequests) // 429
7}

Channel 容量的設定依據：容量 × 每筆事件的記憶體大小 = 背壓 buffer 的記憶體上限。10,000 筆 × 每筆 ~1KB = ~10MB，對多數機器微不足道。

Per-SDK rate limiting

按 source.app（或 API key，啟用認證後）限制每個 SDK 實例的請求速率。防止單一 SDK 的 bug（無限迴圈送事件）打爆 collector。

1// 每個 source.app 一個 rate limiter
2limiter := rateLimiters.GetOrCreate(sourceApp, rate.Limit(100)) // 100 events/sec
3if !limiter.Allow() {
4    w.WriteHeader(http.StatusTooManyRequests)
5    return
6}

Error 快通道

Error 事件不經 rate limit — 它們的 debug 價值最高，且在正常情況下數量遠少於其他類型。Error storm（app 出 bug 導致大量 error）時，error 的量可能暴增，但這正是最需要記錄的時刻。

Error 快通道用獨立的 channel 或跳過 rate limiter 的 check。如果 error 量也超出承載，用第一層的 SDK 端優先級丟棄處理。

第三層：水平擴展

單機的 CPU、記憶體或網路頻寬飽和時，水平擴展 — 多個 collector 實例分攤流量。水平擴展的通用模式見 DevOps 水平擴展。

前提：已切換到 PostgreSQL

SQLite backend 不支援水平擴展。每個 collector 實例有各自的 SQLite 檔案，無法合併查詢。水平擴展的前提是所有 collector 寫入同一個 PostgreSQL。

架構

 1SDK ──→ Load Balancer (nginx / HAProxy)
 2             │
 3        ┌────┴────┐
 4        ▼         ▼
 5   Collector A  Collector B
 6        │         │
 7        └────┬────┘
 8             ▼
 9        PostgreSQL
10             │
11             ▼
12         Dashboard

Collector 實例是 stateless 的 — 不在記憶體保存查詢狀態，所有持久化資料在 PostgreSQL。任何 collector 接收的事件都能被任何 dashboard 查到。

Load balancer 用 round-robin 或 least-connections 分配。不需要 sticky session — collector 不保存 session 狀態。

多機的 Downsample 和 Purge

Downsample 和 Purge job 只能由一個 collector 實例執行（避免重複處理）。用 PostgreSQL 的 advisory lock 或外部的 distributed lock 確保單一執行者。

第四層：Queue 解耦

突發流量超過 collector 群的即時處理能力時，在 collector 和 storage 之間插入 message queue 做緩衝。Queue 緩衝的通用概念見 DevOps 突發流量應對，message queue 的選型見 Backend 模組三 非同步與訊息佇列。

架構

 1SDK ──→ Collector (ingestion only)
 2             │
 3             ▼
 4        Queue (Kafka / NATS / Redis Streams)
 5             │
 6        ┌────┴────┐
 7        ▼         ▼
 8    Worker A   Worker B
 9        │         │
10        └────┬────┘
11             ▼
12        PostgreSQL

Collector 的職責簡化為「接收 → 驗證 → 寫入 queue → 回 202」。寫入 queue 比寫入 DB 快得多（append-only、不需要索引更新），collector 的吞吐上限大幅提升。

Worker 從 queue 消費、寫入 PostgreSQL。Worker 按自己的速度處理 — 高峰時 queue 積壓，高峰過後 worker 消化積壓。Queue 的持久化保證事件不遺失。

Queue 的選擇

自架監控工具的 queue 層級推薦 NATS JetStream — Go 原生 client、單 binary 部署、JetStream 提供持久化和 replay。

觸發條件

Queue 解耦的引入時機是「collector 群已水平擴展但仍無法處理突發流量」。如果日常流量 collector 群能處理，只有行銷活動 / 新聞曝光的短暫高峰需要 queue 緩衝，queue 的維護成本可能高於收益 — 考慮用第一層的動態取樣在源頭降量。

功能分層整合

擴展 功能分層與 Backend 選擇 的分層表，加入 ingestion 維度：

每一層是前一層的超集 — Queue 層包含 PostgreSQL 層的所有查詢能力，加上 ingestion 的 queue 緩衝。

下一步路由

• Collector 的並發寫入策略 → Collector 架構
• Storage 端的擴展設計 → 規模演進
• 功能分層的定義 → 功能分層與 Backend 選擇
• 背壓和流量管控的通用概念 → DevOps 流量管控
• 水平擴展的通用模式 → DevOps 水平擴展
• 突發流量應對 → DevOps 突發流量
• Message queue 選型 → Backend 模組三 非同步與訊息佇列
• 端到端資料完整性（資料損失地圖、完整性指標）→ 端到端資料完整性

單機 Middleware 實作

Rate limit middleware 在 HTTP handler 之前攔截請求。每個 request 過一次 limiter，通過就進入 handler，超限就回 429。

Go 實作

Go 標準生態的 golang.org/x/time/rate 提供 token bucket 的 rate.Limiter。

 1import "golang.org/x/time/rate"
 2
 3// 全域 limiter：每秒 100 個 request、burst 上限 200
 4var globalLimiter = rate.NewLimiter(100, 200)
 5
 6func rateLimitMiddleware(next http.Handler) http.Handler {
 7    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
 8        if !globalLimiter.Allow() {
 9            w.Header().Set("Retry-After", "1")
10            http.Error(w, "Too Many Requests", http.StatusTooManyRequests)
11            return
12        }
13        next.ServeHTTP(w, r)
14    })
15}

Per-client 限速

全域 limiter 對所有 client 共用一個配額。Per-client 限速讓每個 client（by API key、IP、或 tenant ID）有各自的配額。

 1var clients sync.Map // map[string]*rate.Limiter
 2
 3func getClientLimiter(clientID string) *rate.Limiter {
 4    if limiter, ok := clients.Load(clientID); ok {
 5        return limiter.(*rate.Limiter)
 6    }
 7    limiter := rate.NewLimiter(10, 20) // 每 client 每秒 10 個
 8    clients.Store(clientID, limiter)
 9    return limiter
10}

Per-client limiter 用 sync.Map 存、首次出現的 client 自動建立 limiter。長期運行的服務需要定期清理不再活躍的 client limiter（用 goroutine + ticker 掃描最後使用時間）。

回應格式

超限時的 HTTP response 需要帶足夠資訊讓 client 做正確的重試決策。

1HTTP/1.1 429 Too Many Requests
2Retry-After: 1
3X-RateLimit-Limit: 100
4X-RateLimit-Remaining: 0
5X-RateLimit-Reset: 1719014400

Retry-After 告訴 client 等多久再試（秒數或 HTTP date）。X-RateLimit-* headers 不是 RFC 標準但被廣泛使用（GitHub API、Stripe API 都用），讓 client 在被限速前就知道剩餘配額。

分散式限速（Redis-backed）

單機 limiter 的計數存在 process 記憶體中。多個 server instance 各自有獨立的 limiter，client 的請求被 load balancer 分配到不同 instance 時，每個 instance 只看到部分請求 — 全域限速失效。

Redis 做共用的計數儲存，所有 instance 查同一個 counter。

Sliding Window Counter

用 Redis 的 INCR + EXPIRE 實作 sliding window counter。

 1-- Redis Lua script（原子操作）
 2local key = KEYS[1]
 3local limit = tonumber(ARGV[1])
 4local window = tonumber(ARGV[2])
 5
 6local current = redis.call('INCR', key)
 7if current == 1 then
 8    redis.call('EXPIRE', key, window)
 9end
10
11if current > limit then
12    return 0  -- 超限
13end
14return 1      -- 通過

Key 的設計：ratelimit:{client_id}:{endpoint}:{window_start}。Window start 用當前時間截斷到秒或分鐘（如 1719014400），每個窗口一個 key，EXPIRE 自動清理過期窗口。

現成套件

自己寫 Lua script 適合學習，production 用現成套件更可靠：

配額設計

差異化配額

不同的 endpoint 和 client 有不同的配額需求。搜尋 API 比列表 API 消耗更多計算資源，應該有更低的速率上限。

配額溢出的處理

超限時的處理策略依業務需求決定：

Reject（429）：直接拒絕。最簡單，適合 API 服務。Client 收到 429 後按 Retry-After 重試。

Queue（排隊等）：超限的請求進入等待隊列，按順序處理。適合不能丟棄的操作（付款確認、訂單建立）。代價是 client 端等待時間增加。

Degrade（降級回應）：超限時回傳簡化版的回應（cached 結果、摘要而非完整資料）。適合讀取操作。

和 Monitoring 的整合

Rate limit 的命中事件應該記入監控系統，讓團隊知道哪些 client 在撞限速、哪些 endpoint 的配額是否合理。

1// Rate limit hit 時送 metric 事件
2monitor.Metric("ratelimit.hit", map[string]any{
3    "client_id": clientID,
4    "endpoint":  r.URL.Path,
5    "limit":     100,
6    "window":    "1m",
7})

Dashboard 視圖：rate limit hit 的時間趨勢 + 按 client 和 endpoint 分群。Hit 數持續上升代表配額設太低（正常使用被限速）或某個 client 在濫用。

下一步路由

• Rate limit 的概念基礎 → DevOps 流量管控 — Rate Limiting
• 背壓機制（被動的流量控制）→ DevOps 背壓機制
• Rate limit 知識卡 → Rate Limit
• 監控系統中的 ingestion 限速 → Monitoring Ingestion Scaling

概念位置

Rate limit 是容量保護與公平性工具。它可以保護登入、搜尋、匯出、第三方 API、webhook endpoint 與下游服務，降低單一來源耗盡共享資源的風險。 可先對照 Producer。

可觀察訊號與例子

系統需要 rate limit 的訊號是少數使用者或客戶端造成大量 request。匯出報表 API 缺少 rate limit 時，單一 tenant 的批次工作可能佔滿 database connection pool，影響其他 tenant 的正常查詢。

設計責任

限流設計要定義主體、窗口、配額、超限回應、例外權限與觀測欄位。對外 API 要提供清楚的 retry-after 或配額資訊；內部服務要搭配 alert、token bucket 與容量規劃。完整的實作指南（單機 middleware、Redis 分散式限速、配額設計）見 Rate Limit 實作。

監控系統中 per-SDK rate limiting 和偽造流量防護的具體實作見 監控知識卡：Rate Limiting。