Merge pull request #20 from ZhaoChaoqun/feat/telemetry-v1-fine-grained

ZhaoChaoqun · web-flow · commit b82d3416a13a · 2026-03-23T23:38:28.000+08:00
feat: fine-grained telemetry with per-stage latency tracking
diff --git a/Sources/ASREngineFactory.swift b/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)
     }
 
diff --git a/Sources/AnalyticsService.swift b/Sources/AnalyticsService.swift
@@ -0,0 +1,121 @@
+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:
+/// - Latency values use precise milliseconds for maximum diagnostic value
+/// - Text content is NEVER sent; text lengths are bucketed (e.g. "11-50" not "37")
+/// - 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.
+    ///
+    /// Always initializes the SDK regardless of enabled state, so that toggling
+    /// analytics on later doesn't require re-initialization. The `track()` method
+    /// checks `isEnabled` before sending any signals.
+    static func initialize() {
+        let config = TelemetryDeck.Config(appID: appID)
+        TelemetryDeck.initialize(config: config)
+
+        if isEnabled {
+            analyticsLogger.info("Analytics initialized (TelemetryDeck)")
+        } else {
+            analyticsLogger.info("Analytics initialized but disabled by user preference")
+        }
+    }
+
+    /// 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. TelemetryDeck is already initialized;
+    /// this only controls whether `track()` sends signals.
+    static func setEnabled(_ enabled: Bool) {
+        UserDefaults.standard.set(enabled, forKey: "analyticsEnabled")
+        analyticsLogger.info("Analytics \(enabled ? "enabled" : "disabled")")
+    }
+
+    /// 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"] = "\(hasCloudRewriteAPIKey)"
+
+        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+"
+        }
+    }
+
+    /// 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+"
+        }
+    }
+
+    // MARK: - Private Helpers
+
+    /// Whether a Cloud Rewrite API key is configured (user-provided or built-in).
+    private static var hasCloudRewriteAPIKey: Bool {
+        let userKey = UserDefaults.standard.string(forKey: "cloudRewriteAPIKey") ?? ""
+        return !userKey.isEmpty || GeneratedSecrets.cloudRewriteAPIKey != nil
+    }
+}
diff --git a/Sources/PostProcessingPipeline.swift b/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,48 @@ 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 {
+                        Self.trackPostProcessingCompleted(
+                            pipelineStart: pipelineStart,
+                            termNormMs: termNormMs, termNormChanged: termNormChanged,
+                            itnMs: itnMs, itnApplied: itnApplied,
+                            cscMs: 0, cscApplied: false,
+                            punctMs: 0, punctuationApplied: false,
+                            cloudRewriteMs: cloudRewriteMs
+                        )
                         logger.info("最终结果: \(rewrittenText, privacy: .public)")
                         completion(rewrittenText)
                     }
@@ -86,26 +109,69 @@ 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 {
+                    Self.trackPostProcessingCompleted(
+                        pipelineStart: pipelineStart,
+                        termNormMs: termNormMs, termNormChanged: termNormChanged,
+                        itnMs: itnMs, itnApplied: itnApplied,
+                        cscMs: cscMs, cscApplied: cscApplied,
+                        punctMs: punctMs, punctuationApplied: punctuationApplied,
+                        cloudRewriteMs: cloudRewriteMs
+                    )
                     completion(rewrittenText)
                 }
             }
         }
     }
+
+    // MARK: - Analytics Helper
+
+    /// Build and send the PostProcessing.Completed event with per-stage latency.
+    /// Single source of truth — called from both pipeline branches.
+    private static func trackPostProcessingCompleted(
+        pipelineStart: ContinuousClock.Instant,
+        termNormMs: Int, termNormChanged: Bool,
+        itnMs: Int, itnApplied: Bool,
+        cscMs: Int, cscApplied: Bool,
+        punctMs: Int, punctuationApplied: Bool,
+        cloudRewriteMs: Int
+    ) {
+        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)",
+        ])
+    }
 }
diff --git a/Sources/RecordingManager.swift b/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))
         }
     }
diff --git a/Sources/SettingsGeneralView.swift b/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)
+        }
     }
 }
diff --git a/Sources/TypelessApp.swift b/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() {
diff --git a/Typeless.xcodeproj/project.pbxproj b/Typeless.xcodeproj/project.pbxproj
diff --git a/docs/architecture/telemetry-schema-design.md b/docs/architecture/telemetry-schema-design.md
