add sentry session logging

Logs pass/fail for every flash session with console output and device info.
Set VITE_SENTRY_DSN to enable.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

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

Author: adeebshihadeh

.env

@@ -0,0 +1 @@
+VITE_SENTRY_DSN=https://acb8cfad1992fafc3dc90ab1bfa3d07f@o33823.ingest.us.sentry.io/4510604761825280

src/app/Flash.jsx

@@ -1,4 +1,5 @@
 import { useEffect, useRef, useState } from 'react'
+import { addBreadcrumb, setTags, setTag, setContext, captureSessionSummary } from '../utils/telemetry'
 
 import { FlashManager, StepCode, ErrorCode, DeviceType } from '../utils/manager'
 import { useImageManager } from '../utils/image'
@@ -38,9 +39,9 @@ function ImagePreloader() {
   )
 }
 
-// Capture console logs for debug reports
+// Capture console logs for debug reports and telemetry
 const consoleLogs = []
-const MAX_LOGS = 100
+const MAX_LOGS = 500
 const originalConsole = { log: console.log, warn: console.warn, error: console.error, info: console.info, debug: console.debug }
 ;['log', 'warn', 'error', 'info', 'debug'].forEach(level => {
   console[level] = (...args) => {
@@ -50,6 +51,41 @@ const originalConsole = { log: console.log, warn: console.warn, error: console.e
   }
 })
 
+// Unique per-page session id for correlating events
+const SESSION_ID = (crypto && 'randomUUID' in crypto) ? crypto.randomUUID() : String(Math.random()).slice(2)
+
+// Helper for building environment metadata
+function buildEnvMeta() {
+  const ua = navigator.userAgent
+  let os = 'Unknown'
+  if (ua.includes('Windows NT 10.0')) os = 'Windows 10/11'
+  else if (ua.includes('Windows NT 6.3')) os = 'Windows 8.1'
+  else if (ua.includes('Windows NT 6.2')) os = 'Windows 8'
+  else if (ua.includes('Windows NT 6.1')) os = 'Windows 7'
+  else if (ua.includes('Mac OS X')) {
+    const match = ua.match(/Mac OS X (\d+[._]\d+[._]?\d*)/)
+    os = match ? `macOS ${match[1].replace(/_/g, '.')}` : 'macOS'
+  } else if (ua.includes('Linux')) {
+    os = 'Linux'
+    if (ua.includes('Ubuntu')) os += ' (Ubuntu)'
+    else if (ua.includes('Fedora')) os += ' (Fedora)'
+    else if (ua.includes('Debian')) os += ' (Debian)'
+  } else if (ua.includes('CrOS')) os = 'ChromeOS'
+
+  const sandboxHints = []
+  if (ua.includes('snap')) sandboxHints.push('Snap')
+  if (ua.includes('Flatpak')) sandboxHints.push('Flatpak')
+  if (navigator.userAgentData?.brands?.some(b => b.brand.includes('snap'))) sandboxHints.push('Snap')
+
+  return {
+    os,
+    sandbox: sandboxHints.length ? sandboxHints.join(', ') : 'None detected',
+    browser: navigator.userAgent,
+    url: window.location.href,
+    version: import.meta.env.VITE_PUBLIC_GIT_SHA || 'dev',
+  }
+}
+
 // Debug info component for error reporting
 function DebugInfo({ error, step, selectedDevice, serial, message, onClose }) {
   const [copied, setCopied] = useState(false)
@@ -622,6 +658,7 @@ export default function Flash() {
   const [serial, setSerial] = useState(null)
   const [selectedDevice, setSelectedDevice] = useState(null)
   const [wizardScreen, setWizardScreen] = useState('landing') // 'landing', 'device', 'zadig', 'connect', 'unbind', 'webusb', 'flash'
+  const reportSentRef = useRef(false)
 
   const qdlManager = useRef(null)
   const imageManager = useImageManager()
@@ -638,12 +675,34 @@ export default function Flash() {
       .then((programmer) => {
         // Create QDL manager with callbacks that update React state
         qdlManager.current = new FlashManager(programmer, {
-          onStepChange: setStep,
-          onMessageChange: setMessage,
-          onProgressChange: setProgress,
-          onErrorChange: setError,
-          onConnectionChange: setConnected,
-          onSerialChange: setSerial
+          onStepChange: (s) => {
+            setStep(s)
+            addBreadcrumb({ category: 'flash', message: `step:${s}`, level: 'info', data: { step: s } })
+            setTag('last_step', String(s))
+          },
+          onMessageChange: (m) => {
+            setMessage(m)
+            if (m) addBreadcrumb({ category: 'flash', message: m, level: 'info' })
+          },
+          onProgressChange: (p) => {
+            setProgress(p)
+          },
+          onErrorChange: (e) => {
+            setError(e)
+            if (e !== ErrorCode.NONE) {
+              addBreadcrumb({ category: 'flash', message: 'error', level: 'error', data: { errorCode: e } })
+              setTag('error_code', String(e))
+            }
+          },
+          onConnectionChange: (c) => {
+            setConnected(c)
+            addBreadcrumb({ category: 'flash', message: c ? 'connected' : 'disconnected', level: c ? 'info' : 'warning' })
+          },
+          onSerialChange: (sn) => {
+            setSerial(sn)
+            // Avoid tagging the raw serial; keep in context only
+            setContext('device', { serial_present: !!sn })
+          }
         })
 
         // Initialize the manager
@@ -655,6 +714,62 @@ export default function Flash() {
       })
   }, [config, imageManager.current])
 
+  // Telemetry: set static tags/context once
+  useEffect(() => {
+    setTags({ session_id: SESSION_ID })
+    setContext('env', buildEnvMeta())
+  }, [])
+
+  // Telemetry: tag device selection
+  useEffect(() => {
+    if (selectedDevice) {
+      setTag('device_type', selectedDevice)
+      addBreadcrumb({ category: 'flash', message: `device:${selectedDevice}`, level: 'info' })
+    }
+  }, [selectedDevice])
+
+  // Telemetry: wizard screen transitions
+  useEffect(() => {
+    if (wizardScreen) addBreadcrumb({ category: 'wizard', message: wizardScreen, level: 'info' })
+  }, [wizardScreen])
+
+  // Helper to send a single pass/fail summary
+  function sendSessionSummary(result) {
+    if (reportSentRef.current) return
+    reportSentRef.current = true
+    const meta = {
+      ...buildEnvMeta(),
+      selectedDevice,
+      connected,
+      serial_present: !!serial,
+      step,
+      message,
+    }
+    const tail = consoleLogs.slice(-200)
+    captureSessionSummary({
+      sessionId: SESSION_ID,
+      result,
+      errorCode: error,
+      step,
+      meta,
+      consoleTail: tail,
+    })
+  }
+
+  // Send fail on first error
+  useEffect(() => {
+    if (error !== ErrorCode.NONE && !reportSentRef.current) {
+      sendSessionSummary('fail')
+    }
+  }, [error])
+
+  // Send pass when done without error
+  useEffect(() => {
+    if (step === StepCode.DONE && error === ErrorCode.NONE && !reportSentRef.current) {
+      sendSessionSummary('pass')
+    }
+  }, [step, error])
+
   // Transition to flash screen when connected
   useEffect(() => {
     if (connected && wizardScreen === 'webusb') {

src/main.jsx

@@ -1,5 +1,6 @@
 import React from 'react'
 import ReactDOM from 'react-dom/client'
+import { initSentry } from './utils/telemetry'
 
 import '@fontsource-variable/inter'
 import '@fontsource-variable/jetbrains-mono'
@@ -15,6 +16,9 @@ async function loadFonts() {
   ])
 }
 
+// Initialize telemetry (no-op if DSN unset)
+initSentry()
+
 loadFonts().then(() => {
   ReactDOM.createRoot(document.getElementById('root')).render(
     <React.StrictMode>

src/utils/telemetry.js

@@ -0,0 +1,150 @@
+// Lightweight Sentry integration (CDN-based, no-op if DSN unset)
+// - Loads Sentry browser bundle at runtime if a DSN is provided
+// - Exposes helpers to set tags, add breadcrumbs, and send a final session event
+
+let sentryInited = false
+let sentryInitPromise = null
+
+function loadScript(src) {
+  return new Promise((resolve, reject) => {
+    const script = document.createElement('script')
+    script.src = src
+    script.crossOrigin = 'anonymous'
+    script.async = true
+    script.onload = () => resolve()
+    script.onerror = () => reject(new Error(`Failed to load ${src}`))
+    document.head.appendChild(script)
+  })
+}
+
+// Best-effort CDN load for Sentry + Replay. If already present, skips.
+async function ensureSentryBundle() {
+  if (window.Sentry) return
+  // Use a stable recent v7 bundle that includes tracing + replay
+  // If you want to pin a newer version later, update this URL.
+  const url = 'https://browser.sentry-cdn.com/7.114.0/bundle.tracing.replay.min.js'
+  await loadScript(url)
+}
+
+/** Initialize Sentry if `VITE_SENTRY_DSN` is provided. No-op otherwise. */
+export async function initSentry(options = {}) {
+  if (sentryInited || sentryInitPromise) return sentryInitPromise
+
+  const dsn = import.meta.env.VITE_SENTRY_DSN
+  if (!dsn) {
+    // No DSN configured; keep helpers as no-ops
+    sentryInited = false
+    sentryInitPromise = Promise.resolve(false)
+    return sentryInitPromise
+  }
+
+  sentryInitPromise = (async () => {
+    try {
+      await ensureSentryBundle()
+      if (!window.Sentry) return false
+
+      const release = import.meta.env.VITE_PUBLIC_GIT_SHA || 'dev'
+      const environment = import.meta.env.MODE || 'development'
+
+      // Default to replay only on error to keep costs down; can be tuned.
+      window.Sentry.init({
+        dsn,
+        release,
+        environment,
+        // Breadcrumbs already capture console by default; keep it.
+        // Limit traces by default; you can increase later if desired.
+        tracesSampleRate: options.tracesSampleRate ?? 0.0,
+        replaysSessionSampleRate: options.replaysSessionSampleRate ?? 0.0,
+        replaysOnErrorSampleRate: options.replaysOnErrorSampleRate ?? 1.0,
+        maxBreadcrumbs: options.maxBreadcrumbs ?? 100,
+        integrations: [new window.Sentry.Replay({
+          maskAllText: true,
+          blockAllMedia: true,
+        })],
+      })
+
+      sentryInited = true
+      return true
+    } catch (e) {
+      // Swallow init errors to avoid breaking the app
+      // eslint-disable-next-line no-console
+      console.warn('[Sentry] init failed:', e)
+      sentryInited = false
+      return false
+    }
+  })()
+
+  return sentryInitPromise
+}
+
+// Safe no-op wrappers if Sentry isn’t available
+function withSentry(cb) {
+  if (!sentryInited || !window.Sentry) return
+  try { cb(window.Sentry) } catch { /* no-op */ }
+}
+
+export function setTags(tags = {}) {
+  withSentry((S) => S.setTags(tags))
+}
+
+export function setTag(key, value) {
+  withSentry((S) => S.setTag(key, value))
+}
+
+export function setContext(key, context) {
+  withSentry((S) => S.setContext(key, context))
+}
+
+export function addBreadcrumb({ category, message, level = 'info', data }) {
+  withSentry((S) => S.addBreadcrumb({ category, message, level, data }))
+}
+
+/**
+ * Send a compact session summary event with pass/fail and optional console tail.
+ * To keep payloads small, logs are placed in `extra.console_tail` and truncated.
+ */
+export function captureSessionSummary({
+  sessionId,
+  result, // 'pass' | 'fail' | 'abort'
+  errorCode,
+  step,
+  meta = {},
+  consoleTail = [], // Array<{ time, level, message }>
+}) {
+  withSentry((S) => {
+    const level = result === 'pass' ? 'info' : 'error'
+
+    // Attach tags for easier filtering
+    S.setTags({
+      session_id: sessionId,
+      result,
+      error_code: typeof errorCode === 'number' ? String(errorCode) : (errorCode || 'none'),
+      last_step: typeof step === 'number' ? String(step) : (step || 'unknown'),
+    })
+
+    // Try to attach full logs if the SDK supports attachments (v7+ feature; guarded)
+    let usedAttachment = false
+    try {
+      const hasAddAttachment = !!S.addAttachment
+      if (hasAddAttachment && consoleTail && consoleTail.length) {
+        const blob = new Blob([JSON.stringify(consoleTail)], { type: 'application/json' })
+        // Some SDKs attach to current scope and include on next captured event
+        S.addAttachment({ filename: 'console_tail.json', data: blob, contentType: 'application/json' })
+        usedAttachment = true
+      }
+    } catch { /* ignore */ }
+
+    // Always include a compact tail in extras as a fallback
+    const safeTail = (consoleTail || []).slice(-200)
+    S.captureMessage('flash_session', {
+      level,
+      tags: undefined, // tags set via setTags above
+      extra: {
+        usedAttachment,
+        meta,
+        console_tail: safeTail,
+      },
+    })
+  })
+}
+