@tracelog/lib 0.11.4 → 0.12.0

package/README.md

@@ -83,6 +83,13 @@ await tracelog.init({
   // Privacy
   sensitiveQueryParams: ['token'], // Merged with defaults
 
+  // Web Vitals filtering (controls which performance metrics are tracked)
+  webVitalsMode: 'needs-improvement',  // 'all' | 'needs-improvement' | 'poor' (default: 'needs-improvement')
+  webVitalsThresholds: {               // Optional: override default thresholds
+    LCP: 3000,  // Custom threshold in milliseconds
+    FCP: 2000
+  },
+
   // Integrations
   integrations: {
     tracelog: { projectId: 'your-id' },
@@ -164,6 +171,44 @@ tracelog.on('event', (event) => {
 });
 ```
 
+### Web Vitals Filtering
+```typescript
+// Default: Track metrics needing improvement or worse (balanced approach)
+await tracelog.init({
+  webVitalsMode: 'needs-improvement'
+});
+
+// Track all metrics (for full trend analysis and P75 calculations)
+await tracelog.init({
+  webVitalsMode: 'all'
+});
+
+// Track only poor metrics (minimize data volume)
+await tracelog.init({
+  webVitalsMode: 'poor'
+});
+
+// Custom thresholds (fine-grained control)
+await tracelog.init({
+  webVitalsMode: 'needs-improvement',
+  webVitalsThresholds: {
+    LCP: 3000,  // Stricter than default 2500ms
+    FCP: 2500,  // Stricter than default 1800ms
+    CLS: 0.15   // Stricter than default 0.1
+  }
+});
+```
+
+**Threshold Reference (Core Web Vitals standards):**
+
+| Metric | 'all' | 'needs-improvement' (default) | 'poor' |
+|--------|-------|-------------------------------|--------|
+| LCP | Track all | > 2500ms | > 4000ms |
+| FCP | Track all | > 1800ms | > 3000ms |
+| CLS | Track all | > 0.1 | > 0.25 |
+| INP | Track all | > 200ms | > 500ms |
+| TTFB | Track all | > 800ms | > 1800ms |
+
 ### Global Disable
 ```typescript
 window.__traceLogDisabled = true;
@@ -184,12 +229,22 @@ window.__traceLogDisabled = true;
 
 [Full Security Guide →](./SECURITY.md)
 
-## Error Handling
+## Error Handling & Reliability
+
+TraceLog uses a **persistence-based recovery model** with no in-session retries:
+
+- **Success (2xx)** - Events sent immediately, queue cleared
+- **Permanent errors (4xx)** - Events discarded immediately (invalid data won't succeed on retry)
+- **Temporary errors (5xx/network)** - Events removed from queue and persisted to localStorage
+- **Recovery** - Persisted events automatically recovered and retried on next page load
+- **Expiration** - Persisted events expire after 2 hours
+- **Page unload** - Uses `sendBeacon()` for synchronous delivery of session end events
 
-- **4xx errors** - Events discarded (no retry)
-- **5xx/network errors** - Events persist in localStorage for next-page recovery
-- **Page unload** - Uses `sendBeacon()` for reliable delivery
-- **Event expiry** - Persisted events expire after 2 hours
+**Why no in-session retries?**
+- Prevents infinite retry loops during API outages
+- Reduces server load and network traffic during failures
+- Better battery life on mobile devices
+- Natural recovery on page navigation (common in SPAs)
 
 ## Debug