跟 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 與去重分群

本文是 Sentry 的 vendor deep article，深化 overview「Release / source map」跟「Session Replay」段。初次接觸 Sentry 的讀者建議先讀 Sentry 服務頁。

問題情境

Release tracking 讓 Sentry 從「error 收集器」升級成「部署品質追蹤器」。每次部署標記一個 release，Sentry 自動計算 crash-free sessions、regressed errors 跟 release health。Session Replay 進一步把 error 的觸發脈絡從 stack trace 擴展到使用者操作錄影。兩者搭配使用時，團隊能看到「這個版本部署後、哪些使用者遇到什麼操作導致什麼錯誤」的完整鏈路。

Release Health

核心概念

Release health 追蹤每個版本的使用者體驗品質。核心指標：

Crash-free sessions 跟 crash-free users 的差異：sessions 是頻率加權（一個使用者一天開 10 次 app，10 次都算），users 是去重的。Mobile app 通常看 crash-free users（使用者感知），web 通常看 crash-free sessions（頻率反映服務品質）。

Release 標記

在 SDK 初始化時傳入 release 標記：

1sentry_sdk.init(
2    dsn="...",
3    release="checkout-api@1.2.3",
4    environment="production",
5)

Release 命名慣例：<service>@<version> 或 git SHA。用語意版本方便比較，用 git SHA 方便對應 commit。CI/CD pipeline 在 deploy step 自動設定。

Deploy 標記

Release 建立後，用 Sentry CLI 或 API 標記 deploy：

1sentry-cli releases deploys checkout-api@1.2.3 new \
2  --env production \
3  --started $(date -u +%s) \
4  --finished $(date -u +%s)

Deploy 標記讓 Sentry 知道某個 release 何時部署到哪個環境。issue list 的 “First seen in release” 跟 “Regressed in release” 依賴這個資訊。

Regressed Error 偵測

Sentry 會追蹤已 resolve 的 issue。如果新 release 重新觸發了已 resolve 的 issue，Sentry 標記為 regression。這比人工追蹤有效 — 團隊不需要記住哪些 bug 修過，Sentry 自動偵測回歸。

Regression 通知的準確度取決於 grouping 品質。如果 grouping 不準（見 Error Grouping 與 Fingerprinting），regression 偵測也會不準 — 不同 bug 被合成同一 issue 時，resolve 一個 bug 後另一個觸發會被誤判為 regression。

Source map 上傳

前端 minified code 的 stack trace 不可讀。上傳 source map 讓 Sentry 還原原始 source code 位置：

1sentry-cli releases files checkout-api@1.2.3 upload-sourcemaps \
2  --url-prefix '~/static/js' \
3  ./build/static/js

Source map 上傳必須在 deploy 前完成，且 release 版本跟前端 build 版本一致。版本不一致時，Sentry 找不到對應的 source map，stack trace 仍然是 minified。

CI/CD 整合：在 build step 之後、deploy step 之前上傳 source map。多數框架（Next.js、Vite、Webpack）有 Sentry plugin 自動處理。

Session Replay

核心能力

Session Replay 錄製使用者在網頁上的操作。Sentry 記錄的是 DOM mutation 跟使用者事件的結構化資料，播放時 replay DOM 變化，效果類似影片但資料量遠小於螢幕錄影。

replay 跟 error 關聯：Sentry 在 error event 中附帶 replay ID，讓工程師從 issue detail 直接跳到 error 發生前後的使用者操作。

隱私設定

Session Replay 預設會遮罩敏感資訊：

PII 合規考量：

• 預設 maskAllText: true + maskAllInputs: true 是安全起點
• GDPR / CCPA 場景需要額外確認：replay 資料存在 Sentry SaaS（美國資料中心），跨境傳輸需要評估
• Self-hosted Sentry 可以把 replay 資料留在自己的基礎設施

Sampling 策略

Session Replay 會增加前端 SDK 的 payload 大小跟 Sentry 的 event quota。用 sampling rate 控制：

1Sentry.init({
2  dsn: "...",
3  replaysSessionSampleRate: 0.1,  // 10% 的 session 錄影
4  replaysOnErrorSampleRate: 1.0,  // error 發生時 100% 錄影
5});

推薦策略：replaysSessionSampleRate 用低值（1-10%），replaysOnErrorSampleRate 用 100%。目的是確保每個 error 都有 replay 可看，但不錄所有正常 session。

高流量網站（每日百萬 session 以上）可能需要把 replaysSessionSampleRate 設到 0，只在 error 時才錄。session replay 的 quota 消耗速度可以在 Sentry Usage Stats 頁面監控。

Performance Monitoring

Transaction-based tracing

Sentry 的 performance monitoring 用 transaction / span 結構（跟 OpenTelemetry 的 trace / span 概念對齊）。每個 HTTP request、page load 或自訂操作是一個 transaction，transaction 內的子操作是 span。

1with sentry_sdk.start_transaction(op="checkout", name="POST /api/checkout"):
2    with sentry_sdk.start_span(op="db", description="insert order"):
3        # DB operation
4        pass
5    with sentry_sdk.start_span(op="http", description="payment gateway"):
6        # External API call
7        pass

自動 instrumentation 會自動建立 transaction 跟 span（HTTP framework、DB driver、HTTP client）。手動 span 用在自訂業務邏輯或自動 instrumentation 沒覆蓋的路徑。

OTel context 整合

Sentry SDK 支援 OTel context propagation — 如果 upstream service 用 OTel SDK 產生 trace，Sentry SDK 會接受 traceparent header 中的 trace_id 跟 parent_span_id，把自己的 transaction 接到同一條 trace。

整合方式：

常見架構：backend service 用 OTel SDK + Collector，frontend 用 Sentry SDK（前端 error tracking 跟 session replay 是 Sentry 的強項）。兩者透過 trace_id 關聯，在 Sentry 看 frontend error + replay，在 OTel backend 看 backend trace。

Web Vitals

前端 SDK 自動收集 Core Web Vitals（LCP、FID / INP、CLS）跟 TTFB。這些指標跟 error 在同一個 dashboard，讓團隊在 release 後同時看 error regression 跟效能 regression。

Web Vitals 的觀測不需要額外設定 — 前端 SDK 自動收集。但 sampling rate 會影響資料量 — tracesSampleRate 設太低時，Web Vitals 的 sample 數量可能不夠做統計比較。

Self-hosted vs SaaS

決策維度

何時選 self-hosted

資料必須留在特定地理區域（GDPR / 特定產業法規）、或企業 security policy 不允許 error data 送到第三方 — 這是 self-hosted 的核心理由。

Self-hosted Sentry 的維運成本常被低估：20+ 個容器（Kafka、ClickHouse、PostgreSQL、Redis、Snuba、Relay 等）、升級可能需要資料庫 migration、troubleshooting 時沒有 vendor 支援。中小團隊通常 SaaS 的 event pricing 比 self-hosted 的人力成本低。

混合模式

部分團隊用混合模式：production error 送 Sentry SaaS（低維運），但 audit-sensitive 的資料（PII-heavy environment）走 self-hosted。兩套 Sentry instance 各自獨立，不共享 issue。

整合與下一步

• Error grouping 策略：在 issue 數量失控前建立 fingerprint rule，見 Error Grouping 與 Fingerprinting
• 觀測證據整合：把 Sentry issue link 放進 evidence package，見 4.20 Observability Evidence Package
• Client-side monitoring：Sentry 的前端 SDK 跟 RUM 的定位互補，見 4.10 Client-side Monitoring
• 事故響應整合：Sentry alert → PagerDuty / incident.io，見 08 Incident Response 模組