Client Performance Monitoring

3 collapsed lines
1
// Using the raw Performance API
2
new PerformanceObserver((entryList) => {
3
  const entries = entryList.getEntries()
4
  // The last entry is the current LCP candidate
5
  const lastEntry = entries[entries.length - 1] as LargestContentfulPaint
6

7
  console.log("LCP:", lastEntry.startTime)
8
  console.log("Element:", lastEntry.element)
9
  console.log("Size:", lastEntry.size)
10
  console.log("URL:", lastEntry.url) // For images
11
}).observe({ type: "largest-contentful-paint", buffered: true })

3 collapsed lines
1
// Using web-vitals library (recommended)
2
import { onINP } from "web-vitals/attribution"
3

4
onINP((metric) => {
5
  console.log("INP:", metric.value)
6
  console.log("Rating:", metric.rating)
7

8
  // Attribution data for debugging
9
  const { eventTarget, eventType, loadState } = metric.attribution
10
  console.log("Element:", eventTarget)
11
  console.log("Event:", eventType)
12
  console.log("Load state:", loadState) // 'loading', 'dom-interactive', 'dom-content-loaded', 'complete'
13
})

3 collapsed lines
1
// Raw API approach (simplified)
2
let clsValue = 0
3
let clsEntries: LayoutShift[] = []
4

5
new PerformanceObserver((entryList) => {
6
  for (const entry of entryList.getEntries() as LayoutShift[]) {
7
    // Only count unexpected shifts
8
    if (!entry.hadRecentInput) {
9
      clsValue += entry.value
10
      clsEntries.push(entry)
11
    }
12
  }
13
}).observe({ type: "layout-shift", buffered: true })
14

15
// Note: This simplified version doesn't implement session windowing
16
// Use web-vitals library for correct CLS calculation

5 collapsed lines
1
interface PerformanceMetricCallback {
2
  (entries: PerformanceEntryList): void
3
}
4

5
function observePerformance(
6
  entryType: string,
7
  callback: PerformanceMetricCallback,
8
  options: { buffered?: boolean } = {},
9
): () => void {
10
  // Check if entry type is supported
11
  if (!PerformanceObserver.supportedEntryTypes.includes(entryType)) {
12
    console.warn(`Entry type "${entryType}" not supported`)
13
    return () => {}
14
  }
15

16
  const observer = new PerformanceObserver((list) => {
17
    callback(list.getEntries())
18
  })
19

20
  observer.observe({
21
    type: entryType,
22
    buffered: options.buffered ?? true,
23
  })
24

25
  return () => observer.disconnect()
26
}
27

28
// Usage
29
const disconnect = observePerformance("largest-contentful-paint", (entries) => {
30
  const lcp = entries[entries.length - 1]
31
  console.log("LCP:", lcp.startTime)
32
})

3 collapsed lines
1
function getNavigationMetrics(): Record<string, number> {
2
  const [nav] = performance.getEntriesByType("navigation") as PerformanceNavigationTiming[]
3

4
  if (!nav) return {}
5

6
  return {
7
    // DNS
8
    dnsLookup: nav.domainLookupEnd - nav.domainLookupStart,
9

10
    // TCP connection
11
    tcpConnect: nav.connectEnd - nav.connectStart,
12

13
    // TLS handshake (if HTTPS)
14
    tlsHandshake: nav.secureConnectionStart > 0 ? nav.connectEnd - nav.secureConnectionStart : 0,
15

16
    // Time to First Byte
17
    ttfb: nav.responseStart - nav.requestStart,
18

19
    // Download time
20
    downloadTime: nav.responseEnd - nav.responseStart,
21

22
    // DOM processing
23
    domProcessing: nav.domContentLoadedEventEnd - nav.responseEnd,
24

25
    // Total page load
26
    pageLoad: nav.loadEventEnd - nav.startTime,
27

28
    // Transfer size
29
    transferSize: nav.transferSize,
4 collapsed lines
30
    encodedBodySize: nav.encodedBodySize,
31
    decodedBodySize: nav.decodedBodySize,
32
  }
33
}

5 collapsed lines
1
interface ResourceMetrics {
2
  name: string
3
  initiatorType: string
4
  duration: number
5
  transferSize: number
6
  cached: boolean
7
}
8

9
function getSlowResources(threshold = 1000): ResourceMetrics[] {
10
  const resources = performance.getEntriesByType("resource") as PerformanceResourceTiming[]
11

12
  return resources
13
    .filter((r) => r.duration > threshold)
14
    .map((r) => ({
15
      name: r.name,
16
      initiatorType: r.initiatorType,
17
      duration: r.duration,
18
      transferSize: r.transferSize,
19
      cached: r.transferSize === 0 && r.decodedBodySize > 0,
20
    }))
21
    .sort((a, b) => b.duration - a.duration)
22
}
23

24
// Monitor resources as they load
25
new PerformanceObserver((list) => {
26
  for (const entry of list.getEntries() as PerformanceResourceTiming[]) {
27
    if (entry.duration > 2000) {
28
      console.warn("Slow resource:", entry.name, entry.duration)
29
    }
30
  }
31
}).observe({ type: "resource", buffered: true })

3 collapsed lines
1
// Detect long animation frames with attribution
2
new PerformanceObserver((list) => {
3
  for (const entry of list.getEntries() as PerformanceLongAnimationFrameTiming[]) {
4
    console.log("Long frame:", entry.duration, "ms")
5

6
    // Scripts that contributed to the long frame
7
    for (const script of entry.scripts) {
8
      console.log("  Script:", script.sourceURL)
9
      console.log("  Function:", script.sourceFunctionName)
10
      console.log("  Duration:", script.duration, "ms")
11
      console.log("  Invoker:", script.invoker) // 'user-callback', 'event-listener', etc.
12
    }
13
  }
14
}).observe({ type: "long-animation-frame", buffered: true })

3 collapsed lines
1
// Mark a point in time
2
performance.mark("feature-start")
3

4
// ... feature code executes ...
5

6
performance.mark("feature-end")
7

8
// Measure between marks
9
performance.measure("feature-duration", "feature-start", "feature-end")
10

11
// Measure from navigation start
12
performance.measure("time-to-feature", {
13
  start: 0, // navigationStart
14
  end: "feature-start",
15
})
16

17
// Retrieve measures
18
const measures = performance.getEntriesByType("measure")
19
for (const measure of measures) {
20
  console.log(`${measure.name}: ${measure.duration}ms`)
21
}
22

23
// Include custom data (Performance API Level 3)
24
performance.mark("api-call-complete", {
25
  detail: {
26
    endpoint: "/api/users",
27
    status: 200,
28
    cached: false,
29
  },
30
})

5 collapsed lines
1
interface PerformancePayload {
2
  url: string
3
  sessionId: string
4
  timestamp: number
5
  metrics: Record<string, number>
6
  attribution?: Record<string, unknown>
7
}
8

9
class MetricsCollector {
10
  private buffer: PerformancePayload[] = []
11
  private endpoint: string
12
  private maxBufferSize = 10
13

14
  constructor(endpoint: string) {
15
    this.endpoint = endpoint
16
    this.setupUnloadHandler()
17
  }
18

19
  record(metrics: Record<string, number>, attribution?: Record<string, unknown>): void {
20
    this.buffer.push({
21
      url: location.href,
22
      sessionId: this.getSessionId(),
23
      timestamp: Date.now(),
24
      metrics,
25
      attribution,
26
    })
27

28
    // Flush if buffer is full
29
    if (this.buffer.length >= this.maxBufferSize) {
30
      this.flush()
31
    }
32
  }
33

34
  private flush(): void {
35
    if (this.buffer.length === 0) return
36

37
    const payload = JSON.stringify(this.buffer)
38
    this.buffer = []
39

40
    // Try sendBeacon first
41
    const sent = navigator.sendBeacon(this.endpoint, payload)
42

43
    // Fallback to fetch with keepalive
44
    if (!sent) {
16 collapsed lines
45
      fetch(this.endpoint, {
46
        method: "POST",
47
        body: payload,
48
        keepalive: true,
49
        headers: { "Content-Type": "application/json" },
50
      }).catch(() => {
51
        // Silently fail - analytics shouldn't break the page
52
      })
53
    }
54
  }
55

56
  private setupUnloadHandler(): void {
57
    // visibilitychange is more reliable than unload/beforeunload
58
    document.addEventListener("visibilitychange", () => {
59
      if (document.visibilityState === "hidden") {
60
        this.flush()
61
      }
62
    })
63

64
    // Fallback for browsers that don't fire visibilitychange
65
    window.addEventListener("pagehide", () => this.flush())
66
  }
67

68
  private getSessionId(): string {
69
    let id = sessionStorage.getItem("perf_session_id")
70
    if (!id) {
71
      id = crypto.randomUUID()
72
      sessionStorage.setItem("perf_session_id", id)
73
    }
74
    return id
75
  }
76
}

5 collapsed lines
1
type SamplingDecision = "always" | "sampled" | "never"
2

3
interface SamplingConfig {
4
  performanceRate: number // 0-1, e.g., 0.1 = 10%
5
  errorRate: number // Usually 1.0 (100%)
6
  sessionBased: boolean // Decide once per session
7
}
8

9
class Sampler {
10
  private config: SamplingConfig
11
  private sessionDecision: boolean | null = null
12

13
  constructor(config: SamplingConfig) {
14
    this.config = config
15

16
    if (config.sessionBased) {
17
      this.sessionDecision = this.makeDecision(config.performanceRate)
18
    }
19
  }
20

21
  shouldSample(type: "performance" | "error"): boolean {
22
    // Always capture errors
23
    if (type === "error") {
24
      return this.makeDecision(this.config.errorRate)
25
    }
26

27
    // Use session decision if configured
28
    if (this.config.sessionBased && this.sessionDecision !== null) {
29
      return this.sessionDecision
30
    }
31

32
    return this.makeDecision(this.config.performanceRate)
33
  }
34

35
  private makeDecision(rate: number): boolean {
36
    return Math.random() < rate
37
  }
38
}
39

10 collapsed lines
40
// Usage
41
const sampler = new Sampler({
42
  performanceRate: 0.1, // 10% of sessions
43
  errorRate: 1.0, // 100% of errors
44
  sessionBased: true, // Consistent within session
45
})
46

47
if (sampler.shouldSample("performance")) {
48
  collector.record(metrics)
49
}

5 collapsed lines
1
import { onLCP, onINP, onCLS } from "web-vitals/attribution"
2

3
function collectWithAttribution(): void {
4
  onLCP((metric) => {
5
    const { element, url, timeToFirstByte, resourceLoadDelay, resourceLoadDuration, elementRenderDelay } =
6
      metric.attribution
7

8
    sendMetric({
9
      name: "LCP",
10
      value: metric.value,
11
      attribution: {
12
        element: element?.tagName,
13
        elementId: element?.id,
14
        url,
15
        ttfb: timeToFirstByte,
16
        resourceLoadDelay,
17
        resourceLoadDuration,
18
        elementRenderDelay,
19
      },
20
    })
21
  })
22

23
  onINP((metric) => {
24
    const { eventTarget, eventType, loadState, interactionTargetElement, longAnimationFrameEntries } =
25
      metric.attribution
26

27
    sendMetric({
28
      name: "INP",
29
      value: metric.value,
30
      attribution: {
31
        eventTarget,
32
        eventType,
33
        loadState,
34
        element: interactionTargetElement?.tagName,
35
        longFrames: longAnimationFrameEntries?.length,
36
      },
37
    })
38
  })
39

40
  onCLS((metric) => {
41
    const { largestShiftTarget, largestShiftTime, largestShiftValue, loadState } = metric.attribution
42

43
    sendMetric({
44
      name: "CLS",
45
      value: metric.value,
46
      attribution: {
47
        shiftTarget: largestShiftTarget?.tagName,
48
        shiftTime: largestShiftTime,
49
        shiftValue: largestShiftValue,
50
        loadState,
51
      },
52
    })
53
  })
54
}

8 collapsed lines
1
interface ErrorReport {
2
  type: "runtime" | "resource" | "promise" | "network"
3
  message: string
4
  stack?: string
5
  source?: string
6
  line?: number
7
  column?: number
8
  timestamp: number
9
  url: string
10
  userAgent: string
11
}
12

13
class ErrorTracker {
14
  private endpoint: string
15
  private buffer: ErrorReport[] = []
16

17
  constructor(endpoint: string) {
18
    this.endpoint = endpoint
19
    this.setupHandlers()
20
  }
21

22
  private setupHandlers(): void {
23
    // Runtime errors (synchronous)
24
    window.onerror = (message, source, line, column, error) => {
25
      this.report({
26
        type: "runtime",
27
        message: String(message),
28
        stack: error?.stack,
29
        source,
30
        line: line ?? undefined,
31
        column: column ?? undefined,
32
      })
33
      return false // Don't suppress default handling
34
    }
35

36
    // Unhandled promise rejections
37
    window.addEventListener("unhandledrejection", (event) => {
38
      this.report({
39
        type: "promise",
40
        message: event.reason?.message || String(event.reason),
41
        stack: event.reason?.stack,
42
      })
43
    })
44

45
    // Resource loading errors (images, scripts, stylesheets)
46
    window.addEventListener(
47
      "error",
48
      (event) => {
49
        // Only handle resource errors, not runtime errors
50
        if (event.target !== window && event.target instanceof HTMLElement) {
51
          const target = event.target as HTMLImageElement | HTMLScriptElement | HTMLLinkElement
52
          this.report({
53
            type: "resource",
54
            message: `Failed to load ${target.tagName.toLowerCase()}`,
55
            source: (target as HTMLImageElement).src || (target as HTMLLinkElement).href,
56
          })
57
        }
58
      },
59
      true,
60
    ) // Capture phase to catch resource errors
61
  }
62

63
  private report(error: Omit<ErrorReport, "timestamp" | "url" | "userAgent">): void {
64
    const fullError: ErrorReport = {
65
      ...error,
66
      timestamp: Date.now(),
67
      url: location.href,
68
      userAgent: navigator.userAgent,
69
    }
16 collapsed lines
70

71
    this.buffer.push(fullError)
72

73
    // Send immediately for errors (don't batch)
74
    this.flush()
75
  }
76

77
  private flush(): void {
78
    if (this.buffer.length === 0) return
79

80
    const payload = JSON.stringify(this.buffer)
81
    this.buffer = []
82

83
    navigator.sendBeacon(this.endpoint, payload)
84
  }
85
}

5 collapsed lines
1
interface ParsedFrame {
2
  function: string
3
  file: string
4
  line: number
5
  column: number
6
}
7

8
function parseStackTrace(stack: string): ParsedFrame[] {
9
  if (!stack) return []
10

11
  const lines = stack.split("\n")
12
  const frames: ParsedFrame[] = []
13

14
  // Common stack trace formats
15
  const chromeRegex = /at\s+(.+?)\s+\((.+?):(\d+):(\d+)\)/
16
  const firefoxRegex = /(.*)@(.+?):(\d+):(\d+)/
17

18
  for (const line of lines) {
19
    let match = chromeRegex.exec(line) || firefoxRegex.exec(line)
20

21
    if (match) {
22
      frames.push({
23
        function: match[1] || "<anonymous>",
24
        file: match[2],
25
        line: parseInt(match[3], 10),
26
        column: parseInt(match[4], 10),
27
      })
28
    }
29
  }
30

31
  return frames
32
}
33

34
// Server-side: Use source-map library to resolve original locations
35
// Libraries like Sentry, Datadog do this automatically

3 collapsed lines
1
function generateErrorFingerprint(error: ErrorReport): string {
2
  // Group by: type + message pattern + top stack frame
3
  const parts = [error.type, normalizeMessage(error.message), error.stack ? getTopFrame(error.stack) : "no-stack"]
4

5
  return hashString(parts.join("|"))
6
}
7

8
function normalizeMessage(message: string): string {
9
  // Remove dynamic values that would create unique fingerprints
10
  return message
11
    .replace(/\d+/g, "<N>") // Numbers
12
    .replace(/'[^']+'/g, "'<S>'") // Single-quoted strings
13
    .replace(/"[^"]+"/g, '"<S>"') // Double-quoted strings
14
    .replace(/\b[a-f0-9]{8,}\b/gi, "<ID>") // Hex IDs
15
}
16

17
function getTopFrame(stack: string): string {
18
  const frames = parseStackTrace(stack)
19
  if (frames.length === 0) return "unknown"
20

21
  const top = frames[0]
22
  // Use file and line, not column (column varies with minification)
23
  return `${top.file}:${top.line}`
24
}
25

26
function hashString(str: string): string {
27
  // Simple hash for fingerprinting
28
  let hash = 0
29
  for (let i = 0; i < str.length; i++) {
30
    hash = (hash << 5) - hash + str.charCodeAt(i)
31
    hash |= 0
32
  }
33
  return hash.toString(16)
34
}

5 collapsed lines
1
import { onCLS, onINP, onLCP, onFCP, onTTFB } from "web-vitals"
2

3
function sendToAnalytics(metric: { name: string; value: number; delta: number; id: string; rating: string }): void {
4
  const body = JSON.stringify({
5
    name: metric.name,
6
    value: metric.value,
7
    delta: metric.delta,
8
    id: metric.id,
9
    rating: metric.rating,
10
    page: location.pathname,
11
  })
12

13
  // Use sendBeacon for reliable delivery
14
  navigator.sendBeacon("/api/analytics", body)
15
}
16

17
// Register handlers - call each only once per page
18
onCLS(sendToAnalytics)
19
onINP(sendToAnalytics)
20
onLCP(sendToAnalytics)
21
onFCP(sendToAnalytics)
22
onTTFB(sendToAnalytics)

3 collapsed lines
1
import { onLCP, onINP, onCLS } from "web-vitals/attribution"
2

3
// LCP attribution
4
onLCP((metric) => {
5
  console.log("LCP value:", metric.value)
6
  console.log("LCP element:", metric.attribution.element)
7
  console.log("Resource URL:", metric.attribution.url)
8
  console.log("TTFB:", metric.attribution.timeToFirstByte)
9
  console.log("Resource load delay:", metric.attribution.resourceLoadDelay)
10
  console.log("Element render delay:", metric.attribution.elementRenderDelay)
11
})
12

13
// INP attribution
14
onINP((metric) => {
15
  console.log("INP value:", metric.value)
16
  console.log("Event type:", metric.attribution.eventType)
17
  console.log("Event target:", metric.attribution.eventTarget)
18
  console.log("Load state:", metric.attribution.loadState)
19
  console.log("Long frames:", metric.attribution.longAnimationFrameEntries)
20
})
21

22
// CLS attribution
23
onCLS((metric) => {
24
  console.log("CLS value:", metric.value)
25
  console.log("Largest shift target:", metric.attribution.largestShiftTarget)
26
  console.log("Largest shift value:", metric.attribution.largestShiftValue)
27
  console.log("Largest shift time:", metric.attribution.largestShiftTime)
28
})