feat: add fine-grained telemetry with per-stage latency tracking

Integrate TelemetryDeck SDK and implement v1 analytics optimized for
free-tier quota (max 4 events per recording session). Key changes:

- Add AnalyticsService with elapsedMs() helper and privacy-safe buckets
- Enhance PostProcessing.Completed with per-stage precise ms latency
  (TermNorm, ITN, CSC, Punctuation, CloudRewrite)
- Add ASR.FlushCompleted event for core ASR flush performance
- Add Model.LoadCompleted event for model initialization tracking
- Add App.Launched and Session.Completed baseline events
- Add analytics opt-out toggle in Settings UI
- Update telemetry schema design doc to v1.1

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: ZhaoChaoqun

Sources/ASREngineFactory.swift

@@ -33,6 +33,7 @@ enum ASREngineFactory {
         recognitionQueue: DispatchQueue
     ) async -> Result {
         logger.info("开始加载语音识别模型 (\(modelType.displayName, privacy: .public))")
+        let loadStart = ContinuousClock.now
 
         // Clear previous pipeline state
         pipeline.reset()
@@ -57,6 +58,19 @@ enum ASREngineFactory {
         }
         pipeline.termNormalizer = termNormalizer
 
+        // Analytics: track model load result
+        let loadMs = AnalyticsService.elapsedMs(since: loadStart)
+        let success = engine != nil
+        var params: [String: String] = [
+            "engine": modelType.rawValue,
+            "latencyMs": "\(loadMs)",
+            "success": "\(success)",
+        ]
+        if !success {
+            params["errorType"] = "load_failed"
+        }
+        AnalyticsService.track("Model.LoadCompleted", parameters: params)
+
         return Result(engine: engine)
     }
 

Sources/AnalyticsService.swift

@@ -0,0 +1,126 @@
+import Foundation
+import os
+import TelemetryDeck
+
+private let analyticsLogger = Logger(subsystem: "com.typeless.app", category: "Analytics")
+
+/// Lightweight wrapper around TelemetryDeck for privacy-first analytics.
+///
+/// Design principles:
+/// - All numeric values are bucketed (e.g. "500-1000ms" not "743ms") to prevent re-identification
+/// - Text content is NEVER sent
+/// - Users can opt out via Settings toggle (UserDefaults "analyticsEnabled", default true)
+/// - DEBUG builds are automatically tagged as test signals by TelemetryDeck
+enum AnalyticsService {
+
+    private static let appID = "6EB06114-0222-4BE1-9DDC-BB283B640436"
+
+    /// Initialize TelemetryDeck. Call once from AppDelegate.applicationDidFinishLaunching.
+    static func initialize() {
+        guard isEnabled else {
+            analyticsLogger.info("Analytics disabled by user preference")
+            return
+        }
+
+        let config = TelemetryDeck.Config(appID: appID)
+        TelemetryDeck.initialize(config: config)
+        analyticsLogger.info("Analytics initialized (TelemetryDeck)")
+    }
+
+    /// Whether analytics is enabled (opt-out model: default true).
+    static var isEnabled: Bool {
+        // UserDefaults.standard.object returns nil for unset keys;
+        // treat nil as true (opt-out default).
+        if let value = UserDefaults.standard.object(forKey: "analyticsEnabled") as? Bool {
+            return value
+        }
+        return true
+    }
+
+    /// Update enabled state and reinitialize if needed.
+    static func setEnabled(_ enabled: Bool) {
+        UserDefaults.standard.set(enabled, forKey: "analyticsEnabled")
+        if enabled {
+            let config = TelemetryDeck.Config(appID: appID)
+            TelemetryDeck.initialize(config: config)
+            analyticsLogger.info("Analytics re-enabled")
+        }
+        // TelemetryDeck doesn't have a teardown; disabled state is checked in track()
+    }
+
+    /// Track an analytics event with optional parameters.
+    static func track(_ event: String, parameters: [String: String] = [:]) {
+        guard isEnabled else { return }
+
+        // Attach default parameters
+        var params = parameters
+        params["appVersion"] = Bundle.main.infoDictionary?["CFBundleShortVersionString"] as? String ?? "unknown"
+        params["selectedEngine"] = UserDefaults.standard.string(forKey: "selectedASRModel") ?? "streamingParaformer"
+        params["cloudRewriteEnabled"] = "\(!((UserDefaults.standard.string(forKey: "cloudRewriteAPIKey") ?? "").isEmpty) || GeneratedSecrets.cloudRewriteAPIKey != nil)"
+
+        TelemetryDeck.signal(event, parameters: params)
+    }
+
+    // MARK: - Timing Helpers
+
+    /// Convert a `ContinuousClock.Duration` to integer milliseconds.
+    ///
+    /// Usage:
+    /// ```
+    /// let start = ContinuousClock.now
+    /// // ... work ...
+    /// let ms = AnalyticsService.elapsedMs(since: start)
+    /// ```
+    static func elapsedMs(since start: ContinuousClock.Instant) -> Int {
+        let elapsed = start.duration(to: .now)
+        return Int(elapsed.components.seconds * 1000) + Int(elapsed.components.attoseconds / 1_000_000_000_000_000)
+    }
+
+    // MARK: - Bucketing Helpers
+
+    /// Map millisecond latency to a privacy-safe bucket string.
+    static func latencyBucket(ms: Int) -> String {
+        switch ms {
+        case ..<500: return "0-500ms"
+        case 500..<1000: return "500-1000ms"
+        case 1000..<1500: return "1000-1500ms"
+        case 1500..<2000: return "1500-2000ms"
+        default: return "2000ms+"
+        }
+    }
+
+    /// Fine-grained latency bucket for fast pipeline stages (TermNorm, ITN, etc.).
+    static func fineLatencyBucket(ms: Int) -> String {
+        switch ms {
+        case ..<10: return "0-10ms"
+        case 10..<50: return "10-50ms"
+        case 50..<100: return "50-100ms"
+        case 100..<200: return "100-200ms"
+        case 200..<500: return "200-500ms"
+        case 500..<1000: return "500-1000ms"
+        default: return "1000ms+"
+        }
+    }
+
+    /// Map recording duration (seconds) to a privacy-safe bucket.
+    static func durationBucket(seconds: Double) -> String {
+        switch seconds {
+        case ..<5: return "0-5s"
+        case 5..<15: return "5-15s"
+        case 15..<30: return "15-30s"
+        case 30..<60: return "30-60s"
+        default: return "60s+"
+        }
+    }
+
+    /// Map text length (character count) to a privacy-safe bucket.
+    static func lengthBucket(count: Int) -> String {
+        switch count {
+        case 0: return "0"
+        case 1...10: return "1-10"
+        case 11...50: return "11-50"
+        case 51...200: return "51-200"
+        default: return "200+"
+        }
+    }
+}

Sources/PostProcessingPipeline.swift

@@ -50,6 +50,7 @@ final class PostProcessingPipeline {
     func process(rawText: String, engine: (any ASREngine)?, completion: @escaping (String?) -> Void) {
         processingQueue.async { [weak self] in
             guard let self = self else { return }
+            let pipelineStart = ContinuousClock.now
 
             guard !rawText.isEmpty else {
                 logger.info("最终识别结果: （无）")
@@ -58,26 +59,53 @@ final class PostProcessingPipeline {
             }
 
             // Stage 1: Term normalization (domain-specific)
+            let termNormStart = ContinuousClock.now
             let normalizedText = self.termNormalizer?.normalize(rawText) ?? rawText
-            if normalizedText != rawText {
+            let termNormMs = AnalyticsService.elapsedMs(since: termNormStart)
+            let termNormChanged = normalizedText != rawText
+            if termNormChanged {
                 logger.info("TermNormalizer: \(rawText, privacy: .public) → \(normalizedText, privacy: .public)")
             }
 
             // Stage 2: ITN (inverse text normalization) for engines that need it
             var processedText = normalizedText
+            let itnApplied: Bool
+            let itnMs: Int
             if let engine = engine, engine.needsITN, let itn = self.itn {
+                let itnStart = ContinuousClock.now
+                let before = processedText
                 processedText = itn.normalize(text: processedText)
-                if processedText != normalizedText {
+                itnMs = AnalyticsService.elapsedMs(since: itnStart)
+                itnApplied = processedText != before
+                if itnApplied {
                     logger.info("ITN: \(normalizedText, privacy: .public) → \(processedText, privacy: .public)")
                 }
+            } else {
+                itnApplied = false
+                itnMs = 0
             }
 
             // Branch: engines that don't need punctuation skip CSC + punctuation
             guard let engine = engine, engine.needsPunctuation else {
                 Task { [weak self] in
                     guard let self else { return }
+                    let cloudRewriteStart = ContinuousClock.now
                     let rewrittenText = await self.cloudRewriteService.rewriteOrPassthrough(processedText)
+                    let cloudRewriteMs = AnalyticsService.elapsedMs(since: cloudRewriteStart)
                     self.processingQueue.async {
+                        let totalMs = AnalyticsService.elapsedMs(since: pipelineStart)
+                        AnalyticsService.track("PostProcessing.Completed", parameters: [
+                            "itnApplied": "\(itnApplied)",
+                            "cscApplied": "false",
+                            "punctuationApplied": "false",
+                            "totalLatencyMs": "\(totalMs)",
+                            "termNormLatencyMs": "\(termNormMs)",
+                            "itnLatencyMs": "\(itnMs)",
+                            "cscLatencyMs": "0",
+                            "punctLatencyMs": "0",
+                            "cloudRewriteLatencyMs": "\(cloudRewriteMs)",
+                            "termNormChanged": "\(termNormChanged)",
+                        ])
                         logger.info("最终结果: \(rewrittenText, privacy: .public)")
                         completion(rewrittenText)
                     }
@@ -86,23 +114,44 @@ final class PostProcessingPipeline {
             }
 
             // Stage 3: CSC (Chinese spelling correction)
+            let cscStart = ContinuousClock.now
             let correctedText = self.corrector?.correctSpelling(processedText) ?? processedText
+            let cscMs = AnalyticsService.elapsedMs(since: cscStart)
+            let cscApplied = correctedText != processedText
             logger.info("原始文本: \(processedText, privacy: .public)")
-            if correctedText != processedText {
+            if cscApplied {
                 logger.info("CSC 纠正: \(correctedText, privacy: .public)")
             } else {
                 logger.info("CSC 未修改文本")
             }
 
             // Stage 4: Punctuation
+            let punctStart = ContinuousClock.now
             let punctuatedText = self.punctuator?.addPunctuation(text: correctedText) ?? correctedText
+            let punctMs = AnalyticsService.elapsedMs(since: punctStart)
+            let punctuationApplied = punctuatedText != correctedText
             logger.info("标点处理后: \(punctuatedText, privacy: .public)")
 
             // Stage 5: Cloud rewrite
             Task { [weak self] in
                 guard let self else { return }
+                let cloudRewriteStart = ContinuousClock.now
                 let rewrittenText = await self.cloudRewriteService.rewriteOrPassthrough(punctuatedText)
+                let cloudRewriteMs = AnalyticsService.elapsedMs(since: cloudRewriteStart)
                 self.processingQueue.async {
+                    let totalMs = AnalyticsService.elapsedMs(since: pipelineStart)
+                    AnalyticsService.track("PostProcessing.Completed", parameters: [
+                        "itnApplied": "\(itnApplied)",
+                        "cscApplied": "\(cscApplied)",
+                        "punctuationApplied": "\(punctuationApplied)",
+                        "totalLatencyMs": "\(totalMs)",
+                        "termNormLatencyMs": "\(termNormMs)",
+                        "itnLatencyMs": "\(itnMs)",
+                        "cscLatencyMs": "\(cscMs)",
+                        "punctLatencyMs": "\(punctMs)",
+                        "cloudRewriteLatencyMs": "\(cloudRewriteMs)",
+                        "termNormChanged": "\(termNormChanged)",
+                    ])
                     completion(rewrittenText)
                 }
             }

Sources/RecordingManager.swift

@@ -25,6 +25,9 @@ class RecordingManager {
     private let stateQueue = DispatchQueue(label: "com.typeless.state")
     private var state: RecordingState = .idle
 
+    /// Recording session start time for analytics duration tracking
+    private var sessionStartTime: ContinuousClock.Instant?
+
     /// 计算密集型操作的队列（ASR decoding + post-processing 共用）
     private let recognitionQueue = DispatchQueue(label: "com.typeless.recognition", qos: .userInitiated)
 
@@ -121,6 +124,7 @@ class RecordingManager {
 
         // 开始录音
         case (.ready, .recording):
+            self.sessionStartTime = .now
             DispatchQueue.main.async { self.onRecordingStarted?() }
             self.startRecording()
 
@@ -145,6 +149,18 @@ class RecordingManager {
         // 后处理完成
         case (.postProcessing, .ready):
             if case .postProcessComplete(let finalText) = event {
+                // Analytics: track completed session
+                if let startTime = self.sessionStartTime {
+                    let elapsed = startTime.duration(to: .now)
+                    let durationSeconds = Double(elapsed.components.seconds) + Double(elapsed.components.attoseconds) / 1e18
+                    AnalyticsService.track("Session.Completed", parameters: [
+                        "engine": self.currentModel.rawValue,
+                        "durationBucket": AnalyticsService.durationBucket(seconds: durationSeconds),
+                        "hasResult": "\(finalText != nil && !(finalText?.isEmpty ?? true))",
+                        "resultLengthBucket": AnalyticsService.lengthBucket(count: finalText?.count ?? 0),
+                    ])
+                    self.sessionStartTime = nil
+                }
                 DispatchQueue.main.async { self.onFinalResult?(finalText) }
             }
 
@@ -185,9 +201,17 @@ class RecordingManager {
             return
         }
 
+        let flushStart = ContinuousClock.now
         engine.flush { [weak self] rawText in
             guard let self = self else { return }
+            let flushMs = AnalyticsService.elapsedMs(since: flushStart)
             let text = rawText.isEmpty ? fallbackText : rawText
+            AnalyticsService.track("ASR.FlushCompleted", parameters: [
+                "engine": self.currentModel.rawValue,
+                "latencyMs": "\(flushMs)",
+                "success": "\(!rawText.isEmpty)",
+                "rawTextLengthBucket": AnalyticsService.lengthBucket(count: text.count),
+            ])
             self.handleEvent(.flushComplete(rawText: text))
         }
     }

Sources/SettingsGeneralView.swift

@@ -1,7 +1,9 @@
 import SwiftUI
 
-/// 通用设置视图（快捷键、关于、权限）
+/// 通用设置视图（快捷键、关于、权限、数据分析）
 struct SettingsGeneralView: View {
+    @AppStorage("analyticsEnabled") private var analyticsEnabled = true
+
     var body: some View {
         Section("快捷键") {
             Text("长按 Fn 键开始录音")
@@ -21,5 +23,16 @@ struct SettingsGeneralView: View {
         } footer: {
             Text("Nano Typeless 需要辅助功能权限来监听全局按键，需要麦克风权限来录制语音。")
         }
+
+        Section {
+            Toggle("发送匿名使用统计", isOn: $analyticsEnabled)
+        } header: {
+            Text("数据分析")
+        } footer: {
+            Text("帮助改进 Nano Typeless。不会收集任何文本内容或个人信息。")
+        }
+        .onChange(of: analyticsEnabled) { _, newValue in
+            AnalyticsService.setEnabled(newValue)
+        }
     }
 }

Sources/TypelessApp.swift

@@ -25,6 +25,7 @@ class AppDelegate: NSObject, NSApplicationDelegate {
 
     func applicationDidFinishLaunching(_ notification: Notification) {
         NSApp.setActivationPolicy(.accessory)
+        AnalyticsService.initialize()
         setupStatusBar()
 
         _ = RecordingManager.shared
@@ -45,6 +46,8 @@ class AppDelegate: NSObject, NSApplicationDelegate {
         checkPermissions()
         autoDownloadDefaultModelIfNeeded()
         showOnboardingIfNeeded()
+
+        AnalyticsService.track("App.Launched")
     }
 
     private func showOnboardingIfNeeded() {