跟 Backend 04 的分工：本文從 client-side 使用角度說明 Sentry 的 error tracking、performance monitoring 與 session replay — SDK 怎麼埋、error 怎麼分群、release 怎麼追蹤。Server-side 平台治理（告警路由整合、SLI 指標設計、self-hosted vs SaaS 成本治理、跟 OTel 的整合）見 Backend 04 Sentry vendor page。

Sentry 的核心是 error tracking — 自動捕獲未處理的例外、提供 stack trace、自動分群（grouping）相同 root cause 的 error。在 error tracking 的基礎上，Sentry 擴展了 performance monitoring（transaction / span）和 session replay（重播使用者操作）。

Error tracking

Sentry 的 error tracking 架構有三個層次：SDK 端的自動捕獲、server 端的 issue grouping 和 UI 端的 issue management。

自動捕獲

Sentry SDK 在各平台註冊全域錯誤處理器（和模組三 自動攔截的機制相同）。捕獲到例外後，SDK 收集 stack trace、breadcrumbs（最近的使用者操作）、device context（OS / browser / device model）和自訂 tags，打包成 event 送到 Sentry server。

Issue grouping

Sentry server 收到 error event 後，用 fingerprinting 演算法判斷這個 error 是否和已有的 issue 相同。預設的 fingerprinting 基於 stack trace 的 frame — 如果兩個 error 的 stack trace 指向同一個位置，歸入同一個 issue。

自訂 fingerprint 讓開發者控制 grouping 邏輯。例如：不同使用者觸發的同一個 API error 可能有不同的 stack trace（因為 call site 不同），但 root cause 相同 — 自訂 fingerprint 把它們歸入同一個 issue。

Issue management

每個 issue 有狀態（unresolved / resolved / ignored）、指派（誰負責修復）、趨勢（這個 issue 的發生頻率是上升還是下降）。Sentry 的 UI 提供 issue 列表、趨勢圖、影響範圍（影響多少使用者）。

Performance monitoring

Sentry 的 performance monitoring 用 transaction 和 span 模型（和 OpenTelemetry 的 trace / span 概念相同）。

Transaction 代表一個完整的操作（頁面載入、API 請求處理）。Span 是 transaction 內的子操作（database query、外部 API 呼叫）。Transaction 和 span 的 duration 構成操作的時間分佈。

Performance monitoring 的價值是發現「慢」的問題 — P95 回應時間超過閾值、特定 span 佔了 transaction 80% 的時間。和 error tracking 互補：error 告訴你「什麼壞了」，performance 告訴你「什麼慢了」。

Session replay

Session replay 錄製使用者的操作過程 — DOM 變化、滑鼠移動、點擊事件 — 在 Sentry UI 中重播。開發者可以看到「使用者在觸發 error 之前做了什麼操作」。

Session replay 的實作是 DOM snapshot + mutation recording。記錄的是 DOM 結構的變化（非螢幕錄影），在重播時重建 DOM。資料量比錄影小很多，但仍然是所有 Sentry 功能中資料量最大的。

隱私考量：session replay 會看到使用者輸入的內容（除非做 masking）。Sentry 提供 privacy configuration 控制哪些元素被 mask（輸入框、敏感資料區域）。

自架方案和 Sentry 的差距

Sentry 的核心價值在 issue grouping 和趨勢分析 — 把大量 error event 歸類成可管理的 issue 列表，自動追蹤每個 issue 的趨勢。自架方案用 grep 做不到自動 grouping。

下一步路由

• Firebase 的整合方案 → Firebase 套件
• Datadog 的全棧 APM → Datadog RUM
• 自架 vs 商業的判斷 → 自架 vs 商業的判斷決策表
• 自架方案的 error fingerprint 實作 → Error Fingerprint 與去重分群

和 DevOps dashboard 的差異：DevOps 看「基礎設施是否健康」，Developer 看「程式碼是否正確」。Error 趨勢上升在 DevOps 眼中是「事件量異常」，在 Developer 眼中是「程式碼 bug」。

日常監控視圖

Error 摘要

一個數字卡顯示最近 24 小時的 error 總數 + 和前一天的比較（上升 / 下降 / 持平）。旁邊標注「新 error」數量 — 過去 24 小時首次出現的 error name。

新 error 的偵測邏輯：error.name 在最近 24 小時的事件中存在、但在更早的事件中不存在。這是開發者最需要立即注意的 — 新版本引入的 bug 通常表現為「之前沒見過的 error name」。

Error 列表

表格按 error.name 分群，每行顯示：error 名稱、最近 24 小時出現次數、影響的 session 數、首次出現時間、最近出現時間。按出現次數降序排列。

點擊某行進入 Error 詳情視圖。

 1-- SQLite 層可用
 2SELECT name,
 3       COUNT(*) as count,
 4       COUNT(DISTINCT session_id) as sessions,
 5       MIN(ts) as first_seen,
 6       MAX(ts) as last_seen
 7FROM events
 8WHERE type = 'error'
 9  AND ts >= datetime('now', '-1 day')
10GROUP BY name
11ORDER BY count DESC;

Error 趨勢

折線圖顯示過去 7 天每天的 error 數量。可選按 error.name 過濾看單一 error 的趨勢，或看全部 error 的總趨勢。

趨勢的判讀訊號：

• 穩定持平 → 已知的 recurring error，排優先處理
• 新版本部署後突然上升 → 該版本引入的 regression
• 逐漸上升 → 累積性問題（記憶體洩漏、資源耗盡）

版本健康

按 source.version 分群的 error 率比較。每個版本顯示：error 數量、error rate（error / 總事件比）、最常見的 error name。

版本健康視圖幫助判斷「這個版本該不該 rollback」— 如果新版本的 error rate 顯著高於前一版，rollback 決策有數字依據。

Debug 深入視圖

從日常監控的 Error 列表點擊某個 error 進入深入視圖。

Error 詳情

單個 error name 的完整資訊：

• Stack trace（最近一次出現的 error.data.stack_trace）
• 首次出現時間和總出現次數
• 影響的 session 數和佔比
• 按版本分佈（哪些版本有、哪些沒有）
• 按平台分佈（iOS / Android / Web）
• 最近 10 次出現的時間軸

Session 回放

選擇一個受影響的 session，顯示該 session 的完整事件序列。事件按時間排列，每筆事件顯示類型、名稱、時間、data 摘要。Error 事件用顯眼的樣式標記，讓開發者快速定位「error 發生前使用者做了什麼」。

Session 回放需要同一個 session_id 的所有四類事件。這是 event-enumeration-method 中「Debug — 最近操作」事件的核心消費場景。

1-- SQLite 層可用
2SELECT type, name, ts, data
3FROM events
4WHERE session_id = ?
5ORDER BY ts;

平台分佈

某個 error name 在不同平台和 OS 版本的分佈圖。幫助判斷「這個 error 是全平台問題、還是特定平台的 bug」。

1-- SQLite 層可用
2SELECT json_extract(source, '$.platform') as platform,
3       json_extract(source, '$.os') as os_version,
4       COUNT(*) as count
5FROM events
6WHERE type = 'error' AND name = ?
7GROUP BY platform, os_version;

事件覆蓋確認

Developer dashboard 需要的所有事件在目前的事件設計中已完整覆蓋：

SQLite 層 vs PostgreSQL 層

Developer dashboard 的多數視圖在 SQLite 層就能運作 — 都是單表 GROUP BY 和 WHERE 過濾。

開發者 debug 場景不需要 PostgreSQL — SQLite 層的查詢能力已涵蓋所有核心視圖。PostgreSQL 的需求來自效能指標的高級分析（P95 趨勢），但這屬於效能監控動機而非 debug 動機。

下一步路由

• DevOps dashboard 設計 → DevOps Dashboard 設計
• 中台 dashboard 設計 → 中台 Dashboard 設計
• Error 事件的枚舉方法 → 事件枚舉與補齊檢查
• 功能分層與 Backend 選擇 → 功能分層與 Backend 選擇
• Error fingerprint 分群取代 name 分群 → Error Fingerprint 與去重分群

本文是 Sentry 的 vendor deep article，深化 overview「Issue grouping / fingerprint」段。初次接觸 Sentry 的讀者建議先讀 Sentry 服務頁。

問題情境

Error grouping 決定 Sentry 的使用體驗。Grouping 太粗（不同 bug 被合併成同一個 issue），團隊會漏掉新問題；grouping 太細（同一個 bug 被拆成數百個 issue），issue list 變成 noise。理解 Sentry 的 grouping 演算法跟自訂 fingerprint 機制，才能讓 issue list 反映真實的 bug 數量而非 error event 數量。

預設 Grouping 演算法

Stack trace 為主

Sentry 的預設 grouping 策略以 exception type + stack trace 為核心。兩個 error event 會被歸到同一個 issue，如果它們的 exception type 相同、且 stack trace 的「相關 frame」相同。

「相關 frame」是 Sentry 的判定結果 — 它會過濾掉標準函式庫、框架內部 frame 跟已知 noise frame，只留下 application code frame。這個過濾邏輯叫 stack trace rules，由 Sentry 的 grouping 引擎自動決定。

Grouping 版本

Sentry 的 grouping 演算法有多個版本（稱為 grouping config）。新建的 project 自動用最新版（截至 2024 年是 newstyle:2023-01-11），舊 project 可能還在用舊版。升級 grouping config 會改變 issue 的歸屬 — 之前合併的 event 可能被拆開，之前分開的可能合併。

確認目前的 grouping config：Project Settings → General Settings → Event Grouping。升級前先用 Sentry 的 grouping preview 功能測試影響範圍。

非 exception 事件

沒有 stack trace 的事件（capture_message、breadcrumb-only event、CSP violation）用 message 內容做 grouping。相同 message template 的事件歸到同一個 issue。

message 中如果包含動態值（user ID、request ID、timestamp），Sentry 會嘗試辨識並忽略動態部分。但辨識不完美 — 如果 message 格式不一致，同一種錯誤可能被拆成多個 issue。

自訂 Fingerprint

何時需要自訂

預設 grouping 不夠用的常見場景：

Server-side fingerprint rules

在 Project Settings → Issue Grouping → Fingerprint Rules 設定。語法：

 1# 所有 ConnectionError 歸成一個 issue
 2error.type:ConnectionError -> connection-error
 3
 4# 特定 message pattern 歸成一個 issue
 5message:"Rate limit exceeded*" -> rate-limit
 6
 7# 特定 module 的所有 error 歸成一組
 8module:payment.gateway.* -> payment-gateway-error
 9
10# 組合條件
11error.type:TimeoutError module:external.api.* -> external-api-timeout

Server-side rules 的優先順序：越後面的 rule 優先順序越高。如果一個 event 匹配多條 rule，用最後一條。

SDK-side fingerprint

在 SDK 的 before_send callback 中設定 event.fingerprint：

1def before_send(event, hint):
2    if "ConnectionError" in str(hint.get("exc_info", "")):
3        event["fingerprint"] = ["connection-error"]
4    return event
5
6sentry_sdk.init(dsn="...", before_send=before_send)

SDK-side 跟 server-side 的差異：

優先用 server-side rules — 集中管理、即時生效。SDK-side 用在 server-side rules 表達不了的複雜邏輯。

{{ default }} 組合

Fingerprint 中的 {{ default }} 代表 Sentry 預設的 grouping 結果。跟自訂值組合使用：

1# 用預設 grouping + environment 維度拆分
2fingerprint: ["{{ default }}", "{{ environment }}"]

這樣同一個 bug 在 staging 跟 production 會分成兩個 issue，方便分別追蹤。

Merge 與 Unmerge

事後修正

當 grouping 不準時，Sentry 提供事後修正：

Merge：選擇多個 issue，合併成一個。合併後的 issue 保留所有 event，但只保留一個 issue ID。適合預設 grouping 太細（同一 bug 被拆成多個 issue）的情況。

Unmerge（拆分）：從一個 issue 中選擇部分 event，拆出成新 issue。適合預設 grouping 太粗（不同 bug 被合在同一個 issue）的情況。

Merge/Unmerge 的限制

Merge 跟 Unmerge 都是「貼 OK 繃」— 只影響現有 event，新進的 event 仍然用原來的 grouping 邏輯。如果根因是 grouping 太粗或太細，應該修 fingerprint rule，而非持續 merge/unmerge。

判讀順序：

1. 發現 grouping 不準
2. 先用 merge/unmerge 處理現有 issue（止血）
3. 分析 root cause — 是 stack trace 不穩定、message 有動態值、還是缺 fingerprint rule
4. 加 fingerprint rule 永久修正
5. 驗證新進 event 的 grouping 是否正確

Grouping 不準的判讀

太細的訊號

• Issue list 中出現大量「相似標題但不同 ID」的 issue
• 單一事件只有 1-2 個 occurrence 的 issue 大量出現
• 同一個使用者操作觸發的 error 被分散到多個 issue

常見原因：message 中包含動態值（user ID、timestamp、request path）、source map 缺失（前端）、stack trace 包含 generated code frame。

太粗的訊號

• 一個 issue 的 event 數量持續增長，但 event detail 看起來是不同問題
• Issue 的 status 被 resolve 後馬上 regress，但新 event 跟原因不同
• 團隊 ignore 了一個「雜 issue」但裡面混著真正需要處理的 bug

常見原因：exception type 太通用（RuntimeError、Exception）、fingerprint rule 太粗（把整個 module 的 error 合成一個 issue）。

大量 Unique Errors 的治理

問題：Issue 爆量

project 的 issue 數量超過數千時，issue list 失去可操作性。on-call 打開 Sentry 看到 2000 個 unresolved issue，等於沒有 triage。

治理策略

Inbound filter：在 Project Settings → Inbound Filters 設定，丟棄已知的 noise event（browser extension error、crawler error、legacy browser error）。丟棄在 ingestion 層，不消耗 quota。

Rate limit：project 或 key 級別的 rate limit。超過限額的 event 被丟棄。適合防止單一 bug 的暴增 event 耗盡 quota，但不解決 issue 數量問題。

Alert rule 搭配 ownership：用 Sentry alert rule 把特定 tag（service、team、module）的新 issue 通知對應 team。不是所有 issue 都要同一個人看。

定期 triage cadence：每週或每兩週的 triage session，把 issue 分成 fix / ignore / merge 三類。Sentry 的 For Review tab 自動列出需要初次 triage 的 issue。

Auto-resolve：設定 auto-resolve policy — 超過 N 天沒有新 event 的 issue 自動 resolve。避免舊 issue 永遠佔據 unresolved list。

治理後的穩態

合理的穩態是：unresolved issue 數量穩定在數十到數百，每週新增 issue 跟 resolve issue 數量大致平衡。如果 unresolved 持續增長，先檢查是否有 noise event 沒被 filter，或 fingerprint 太細。

整合與下一步

• Error tracking 跟 observability 的邊界：Sentry 處理 error lifecycle、metrics/logs/traces 處理系統行為，見 4.17 Telemetry Data Quality
• OTel context 整合：Sentry SDK 接受 OTel trace_id / span_id，讓 error 跟 trace 關聯，見 OpenTelemetry Collector 部署模式
• Release tracking 跟 session replay：見 Release Tracking 與 Session Replay
• 事故響應整合：嚴重 issue → alert → on-call，見 08 Incident Response 模組