觀察

app_tunnel 的六個核心元件在實機測試前的 log 覆蓋狀態：

W2-004（P0：iOS 實機 WS stream 不觸發）的 debug 過程：無法從任何 log 判斷問題發生在 biometric → credential → WS connect → auth token → stream listen 的哪一步。開發者被迫在每個函式手動加 developer.log，重新編譯，插拔裝置測試，反覆數次才定位到「stream 訂閱時機」問題。

判讀

1. Log 缺失把 debug 成本從秒級升到分鐘級。如果 ConnectionManager 在企劃階段就設計了「Step 1: biometric → Step 2: credential → Step 3: WS connect → Step 4: auth token → Step 5: listen stream」五步 log，W2-002 的 auth token 問題在第一次連線就能從 log 看到「Step 3 完成，Step 4 未執行」。

2. 「事後補 log」的 log 品質較低。W2 修復時補的 developer.log 格式不統一（有的帶 name:，有的不帶；有的用 // i18n-exempt 標記，有的忘了），沒有統一的 log 層級，沒有結構化欄位。事後補的 log 是救火工具，不是可觀測性設計。

3. 自用工具最適合自架 log 收集。app_tunnel 的 server 和 client 都在同一台機器上（或同一個 Tailscale tailnet），client 可以直接打 HTTP POST 到本機的 log endpoint，不需要 Sentry 或 Crashlytics。一個 Go 寫的 JSON log receiver（20 行）+ grep 就是完整的 debug 工具鏈。

4. Log 設計是功能規格的一部分。「連線到 ttyd 終端機」這個功能的規格不只是「建立 WS 連線」，還包含「每步有 log、失敗有 log、成功有 log」。跟 API 規格需要定義 request/response 一樣，連線功能需要定義 log 點。

策略

1. 功能規格階段列出 log 點清單：每個功能的規格文件新增「可觀測性」欄位，列出啟動/步驟/錯誤/完成四類 log 點。
2. 建立統一 log 層：封裝 developer.log 為 AppLogger，統一 name、level、格式。開發期用 developer.log，後續可切換到 HTTP log endpoint。
3. 自架 log endpoint 方案：本機 Go server 開一個 /log POST endpoint，接收 JSON log，寫入檔案。Client 端 AppLogger 在 debug mode 同時寫 console + POST 到 endpoint。開發期 grep 查詢，不需要 dashboard。
4. Protocol log 獨立一層：WebSocket frame type、payload 前綴、auth handshake 結果獨立記錄，跟 business log 分開。這層 log 在 release mode 應該能關閉。

下一步路由

• 想設計客戶端 log 方案 → 模組二：客戶端可觀測性
• 想理解三層 log 設計 → 三層 log 設計
• 想建自架 log endpoint → 自架 log endpoint vs 商業方案

Debug 動機

Debug 動機驅動的事件收集目標是「問題發生時、開發者能從事件記錄中重建 context 並定位根因」。

要偵測的行為

• 多步驟流程的每一步完成或失敗（連線 → 認證 → 資料交換）
• 系統狀態轉換（前景/背景、連線/斷線、登入/登出）
• 非預期例外（uncaught exception、network error、timeout）
• 使用者最近的操作序列（問題發生前做了什麼）

事件表

查詢場景

Session 回放：按 session_id 過濾、按時間排序，還原「使用者做了什麼 → 系統發生了什麼 → 問題在哪裡出現」。

Error 根因定位：按 error name GROUP BY，找出最常出現的錯誤。單筆 error 的 stack_trace + 同 session 的 lifecycle 事件組合，判斷失敗發生在流程的哪一步。

最近 N 個操作：error 發生前的 10-20 個 event/lifecycle 事件，等同 Sentry 的 breadcrumb trail。

生命週期階段

開發期起全開。Debug 事件是最早需要的 — 實機測試階段就依賴這些事件定位問題。error 類和 lifecycle 類不做取樣（量低且每筆都可能是線索）。

商業動機

商業動機驅動的事件收集目標是「回答產品決策的問題 — 使用者在哪裡流失、不同群組行為有什麼差異、哪些功能被使用」。

要偵測的行為

• 漏斗步驟完成（註冊 → 啟用 → 付費 → 續約的每一步）
• 功能使用頻率（哪些功能被頻繁使用、哪些從未被觸發）
• Session 長度和頻率（使用者多常用、每次用多久）
• 關鍵轉換事件（首次付費、邀請好友、升級方案）

事件表

查詢場景

Funnel 轉換率：每步的完成數 / 上一步的完成數。SQLite 層做每步計數，PostgreSQL 層做 session 級 JOIN 的精確轉換率（見 功能分層與 Backend 選擇）。

Cohort 留存：按「首次使用週」分群，計算每週的回訪率。需要 session.start 事件 + 使用者首次出現的時間戳。

功能使用率：feature.*.used 事件按 name GROUP BY COUNT，排序找出最常/最少使用的功能。

生命週期階段

上線後啟用。開發期不需要商業事件（沒有真實使用者）。測試期可以用模擬流量驗證 funnel 事件的觸發正確性，但不做分析。

資安動機

資安動機驅動的事件收集目標是「偵測非預期的存取模式、追蹤敏感操作、提供事後稽核的 audit trail」。

要偵測的行為

• 認證失敗（密碼錯誤、biometric 失敗、token 過期）
• 權限越界嘗試（嘗試存取非自己的資源、呼叫無權限的 API）
• 敏感資料存取（查看個資、匯出資料、修改權限設定）
• 異常存取模式（短時間大量請求、非常規時段存取、來源 IP 變化）

事件表

查詢場景

認證失敗監控：auth.*.failed 事件的 count by session_id，短時間內同一 session 多次失敗 → 暴力破解嫌疑。Rule engine 設閾值告警。

Audit trail：sensitive.* 和 admin.* 事件按時間排列，回答「誰在什麼時候存取/修改了什麼」。合規審計的必要紀錄。

異常 pattern 偵測：auth 成功後的操作事件頻率和模式分析。正常使用者每 session 操作 10-50 次；自動化腳本可能操作數千次。

生命週期階段

開發期起全開。安全事件不能延後 — 「先不收安全事件、上線後再加」等於安全審計的空白期。認證相關事件是 auto-intercept 的一部分（見 自動攔截機制），不需要手動埋點。

和 redaction 的關係

資安事件本身可能包含敏感資訊（失敗的密碼、被存取的個資欄位名稱）。事件的 data schema 設計時標記需要 redaction 的欄位 — auth.failed 記錄失敗原因但不記錄輸入的密碼、sensitive.accessed 記錄資源類型但不記錄資源內容。

效能動機

效能動機驅動的事件收集目標是「發現效能退化趨勢、定位效能瓶頸、為容量規劃提供數據」。

要偵測的行為

• 操作回應時間（API 呼叫、頁面載入、動畫轉場）
• 渲染效能（frame rate、長任務、佈局重排）
• 資源使用（記憶體、CPU、網路流量）
• 外部依賴延遲（第三方 API、CDN、資料庫查詢）

事件表

查詢場景

P95 趨勢：{operation}.duration 事件按天聚合、計算 percentile_cont(0.95)，觀察回應時間是否隨版本增加。

容量規劃：resource.memory 事件的趨勢圖，判斷記憶體是否隨使用時間穩定增長（memory leak 訊號）。

依賴健康度：dependency.*.latency 事件按 dependency_name GROUP BY，比較各依賴的平均延遲和失敗率。

生命週期階段

測試期起啟用。開發期不需要效能事件（本地環境的效能數據不代表 production）。測試期啟用用於建立效能 baseline。上線後持續收集用於趨勢監控。

效能事件量通常最大（每 30 秒一筆 resource.memory × 活躍使用者數），取樣率需要控制 — 自用場景全收、商業產品取樣 10-50%（見 前端感測器設計 的取樣策略段）。

A/B 測試動機

A/B 測試動機驅動的事件是商業動機的延伸 — 實驗期間收集實驗分組和轉換事件，實驗結束後關閉。

事件表

生命週期階段

實驗期間啟用，實驗結束後關閉（從 SDK config 或 feature flag 移除）。實驗事件的保留期限跟著實驗週期走 — 實驗結束 + 分析完成後可清除。A/B test 的統計分析見 A/B test 的統計基礎。

完整對照總表

下一步路由

• 四類事件的基礎定義 → 四類事件的完整定義
• 事件枚舉的方法論 → 事件枚舉與補齊檢查
• 前端感測器的具體設計 → 前端感測器設計
• 感測器的生命週期控制 → 感測器生命週期管理
• 查詢消費模式的完整展開 → 查詢消費模式

五種查詢場景各自需要不同的事件類型、欄位和查詢模式。每種場景的查詢模式也決定了需要 SQLite 層還是 PostgreSQL 層（見 功能分層與 Backend 選擇）。

Debug 查詢

Debug 查詢回答「問題出在哪」。觸發時機是使用者回報問題或 error alert 觸發後，開發者需要還原問題的 context。

查詢場景

剛才使用者回報的問題

查詢模式：用 session_id 過濾，拉出該 session 的全部事件，按時間排序。

1-- SQLite
2SELECT type, name, ts, data
3FROM events
4WHERE session_id = 'abc-123'
5ORDER BY ts;

需要的事件欄位：session_id（關聯同次使用的事件）、ts（排序）、error 的 stack trace 和 step（定位失敗點）。

這個 error 多常發生

查詢模式：按 error name 分群計數，看時間趨勢。

1-- SQLite
2SELECT name, COUNT(*) as count,
3       strftime('%Y-%m-%d', ts) as day
4FROM events
5WHERE type = 'error'
6  AND ts >= datetime('now', '-7 days')
7GROUP BY name, day
8ORDER BY day, count DESC;

需要的事件欄位：type=‘error’、name（分群鍵）、ts（時間分桶）。

需要的事件

Alerting 查詢

Alerting 查詢回答「需要注意嗎」。分兩種機制：rule engine 的即時評估（事件到達時逐筆比對規則）和事後查詢的趨勢分析。

查詢場景

Error 數量突然上升

查詢模式：最近 1 小時的 error 計數 vs 前一天同時段，偏差超過閾值則告警。

1-- SQLite
2SELECT COUNT(*) as recent_count
3FROM events
4WHERE type = 'error'
5  AND ts >= datetime('now', '-1 hour');

Rule engine 的即時版：每收到一筆 error 事件，遞增計數器，計數器超過閾值觸發動作。

特定 error 首次出現

查詢模式：收到 error 時查是否有歷史記錄。

1-- SQLite
2SELECT COUNT(*) FROM events
3WHERE type = 'error' AND name = ?
4  AND ts < ?;

結果為 0 代表首次出現 — 觸發「新 error 類型」告警。Sentry 的核心功能之一就是這個查詢。

Rule engine vs 事後查詢

Rule engine 逐筆評估，延遲在毫秒級，適合「error 出現就通知」。事後查詢用 SQL 聚合，延遲在秒到分鐘級，適合「過去一小時的 error 趨勢」。兩者互補 — rule engine 做即時告警、SQL 查詢做事後分析。

需要的事件

產品決策查詢

產品決策查詢回答「使用者怎麼用產品」。從簡單的功能使用率到複雜的 funnel 分析。

查詢場景

新功能有多少人用

查詢模式：按 event name 計數。SQLite 層即可。

1-- SQLite
2SELECT name, COUNT(*) as count,
3       COUNT(DISTINCT session_id) as unique_sessions
4FROM events
5WHERE type = 'event'
6  AND name LIKE 'new_feature.%'
7  AND ts >= datetime('now', '-7 days')
8GROUP BY name;

註冊流程在哪流失

查詢模式：session 級 funnel JOIN。需要 PostgreSQL 層。

 1-- PostgreSQL
 2WITH session_steps AS (
 3  SELECT session_id, name,
 4         ROW_NUMBER() OVER (PARTITION BY session_id ORDER BY ts) as step_order
 5  FROM events
 6  WHERE name IN ('signup.start', 'signup.email', 'signup.verify', 'signup.complete')
 7    AND ts >= NOW() - INTERVAL '30 days'
 8)
 9SELECT name, COUNT(DISTINCT session_id) as sessions
10FROM session_steps
11GROUP BY name
12ORDER BY MIN(step_order);

完整的 funnel 分析方法論見 從 collector 資料做基礎 funnel 分析。

需要的事件

安全審計查詢

安全審計查詢回答「有沒有非預期的存取」。重點是偵測異常模式而非單筆事件。

查詢場景

有沒有異常登入

查詢模式：auth 失敗事件按 session 分群計數，短時間內大量失敗 = 暴力破解嘗試。

1-- SQLite
2SELECT session_id, COUNT(*) as fail_count,
3       MIN(ts) as first_attempt, MAX(ts) as last_attempt
4FROM events
5WHERE type = 'error' AND name = 'auth.login.failed'
6  AND ts >= datetime('now', '-1 hour')
7GROUP BY session_id
8HAVING fail_count > 5;

誰存取了什麼敏感資料

查詢模式：敏感操作的 audit trail — 按時間列出所有敏感操作事件。

1-- SQLite
2SELECT ts, session_id, name, data
3FROM events
4WHERE type = 'event'
5  AND name IN ('data.export', 'admin.user_lookup', 'config.secret_read')
6ORDER BY ts DESC;

需要的事件

安全事件的取樣率必須是 1.0（全收）— 取樣會讓攻擊嘗試在統計上隱形。見 感測器生命週期管理 的取樣率設計段。

效能查詢

效能查詢回答「系統有多快」和「哪裡變慢了」。

查詢場景

P95 回應時間趨勢

查詢模式：時間分桶 + percentile 聚合。需要 PostgreSQL 層。

1-- PostgreSQL
2SELECT date_trunc('hour', ts) as hour,
3       percentile_cont(0.95) WITHIN GROUP (ORDER BY (data->>'duration_ms')::int) as p95
4FROM events
5WHERE type = 'metric' AND name = 'api.response.duration'
6  AND ts >= NOW() - INTERVAL '7 days'
7GROUP BY hour
8ORDER BY hour;

SQLite 沒有內建 percentile 函數。SQLite 層的替代方案是排序後取第 95% 位置的值，但在大資料量時效能差。

哪個版本變慢了

查詢模式：按 source.version 分群比較效能。

1-- SQLite / PostgreSQL
2SELECT source_version, AVG((data->>'duration_ms')::int) as avg_ms,
3       COUNT(*) as sample_count
4FROM events
5WHERE type = 'metric' AND name = 'api.response.duration'
6  AND ts >= datetime('now', '-7 days')
7GROUP BY source_version;

需要的事件

查詢 → 事件反推表

設計事件時用這張表反向確認：每種查詢場景需要什麼事件、什麼欄位、什麼 storage 層級。

這張表和 事件枚舉與補齊檢查 的事件表互補 — 事件枚舉從操作端正向推導「要收什麼」，本表從查詢端反向確認「收的夠不夠」。

下一步路由

• 從操作端正向推導事件 → 事件枚舉與補齊檢查
• 動機和事件的對應關係 → 動機驅動的事件設計
• SQLite vs PostgreSQL 的查詢能力分界 → 功能分層與 Backend 選擇
• Rule engine 的即時評估 → Rule engine 設計

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

內容大致分三類：

版控操作 — git rebase / fixup / 移除歷史內容等。例：

• Git：把後面 commit 的部分檔案變更搬到前面的 commit
• Git：修復後面的 commit 意外覆蓋前面 commit 的變更

Build 工具與框架 — Gradle / Flutter / Dart 的錯誤、行為、設計觀念。例：

• gradle_jvm_target_asymmetry — Kotlin/Java target 不一致導致 build 失敗
• gradle_evaluation_order_traps — Gradle configuration phase 時序陷阱
• flutter_hit_test_behavior — Flutter widget hit test 行為

環境、設定與架構觀念 — 開發環境一次性設定、與後端協作時整理出的設計觀念等。

跟其他資料夾的邊界

判斷流程：是「工作場景觸發、想記下來的」？→ work-log。是「blog 內部問題」？→ posts。是「跟工作脈絡無關的方法論整理」？→ record / report。

底下自動列出本資料夾的所有文章、依日期排序。

• Android 裝置系統版本 Android 11 以上
• 電腦與 Android 裝置連接在同一個區域網路
• 已安裝 ADB 工具（通常隨 Android Studio 安裝）

步驟一：啟用無線偵錯

1. 進入 Android 裝置的 設定 → 開發人員選項
2. 開啟 無線偵錯（Wireless debugging）
3. 在彈出的對話框中選擇「允許」

步驟二：配對裝置（首次連接需要）

在 Android 裝置上

1. 點擊 無線偵錯 進入詳細頁面
2. 點擊 使用配對碼配對裝置
3. 記下畫面上顯示的：
   • IP 位址與配對端口（例如：192.168.1.100:45213）
   • 配對碼（6 位數字）

在電腦終端機上

1adb pair <IP>:<配對端口>

範例：

1adb pair 192.168.1.100:45213

輸入配對碼後，看到以下訊息表示配對成功：

1Successfully paired to 192.168.1.100:45213

注意：配對碼有時效性，產生後請盡快輸入

步驟三：連接裝置

在 Android 裝置上

回到無線偵錯主頁面，查看顯示的 IP 位址與連接端口（與配對端口不同）

例如：192.168.1.100:38745

在電腦終端機上

1adb connect <IP>:<連接端口>

範例：

1adb connect 192.168.1.100:38745

看到以下訊息表示連接成功：

1connected to 192.168.1.100:38745

步驟四：驗證連接

1adb devices

或使用 Flutter：

1flutter devices

應該能看到無線連接的裝置列表。

常用指令速查

疑難排解

配對失敗

• 確認電腦與裝置在同一區網
• 檢查路由器是否開啟 AP 隔離功能
• 暫時關閉電腦防火牆測試

連接後無法使用

• 確認使用的是「連接端口」而非「配對端口」
• 嘗試重啟 ADB 服務：adb kill-server && adb start-server

裝置離線或消失

• 無線偵錯可能因裝置休眠而中斷
• 重新執行 adb connect 即可恢復

流程圖

 1┌─────────────────┐
 2│  啟用無線偵錯   │
 3└────────┬────────┘
 4         ▼
 5┌─────────────────┐
 6│  取得配對資訊   │ ← 配對端口 + 配對碼
 7└────────┬────────┘
 8         ▼
 9┌─────────────────┐
10│   adb pair      │ ← 首次連接需要
11└────────┬────────┘
12         ▼
13┌─────────────────┐
14│  取得連接端口   │ ← 無線偵錯主頁面
15└────────┬────────┘
16         ▼
17┌─────────────────┐
18│  adb connect    │
19└────────┬────────┘
20         ▼
21┌─────────────────┐
22│    連接完成     │
23└─────────────────┘