feat: add main-thread blocking detection (Long Tasks + LoAF + web Vitals) by Dobrunia · Pull Request #166 · codex-team/hawk.javascript

Dobrunia · 2026-02-23T17:22:46Z

Summary

Add main-thread freeze detection to JS catcher:
- Long Tasks API
- Long Animation Frames (LoAF)
Add aggregated Web Vitals issues monitoring (LCP, FCP, TTFB, INP, CLS):
- sends one dedicated Hawk issue event when at least one metric is poor
- includes full metrics payload (value, rating, delta) for diagnostics
New unified config:
- issues.errors
- issues.webVitals
- issues.longTasks.thresholdMs
- issues.longAnimationFrames.thresholdMs

Defaults

issues: {  
  errors: true,  
  webVitals: false,  
  longTasks: false, 
  longAnimationFrames: false
}

…and serialization

Copilot

Pull request overview

This PR adds main-thread blocking detection to the JavaScript error catcher using the Long Tasks API and Long Animation Frames (LoAF) API. When a blocking entry is detected (task >50 ms), a dedicated Hawk event is sent immediately with blocking details in the context.

Changes:

Added new longTasks.ts addon that sets up PerformanceObservers for Long Tasks and LoAF APIs
Integrated the observers into the Catcher constructor with configurable options
Added mainThreadBlocking configuration option to HawkInitialSettings

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
packages/javascript/src/addons/longTasks.ts	New addon implementing Long Tasks and LoAF observers with feature detection and data serialization
packages/javascript/src/catcher.ts	Integrated main-thread blocking detection into the constructor with callback to send()
packages/javascript/src/types/hawk-initial-settings.ts	Added mainThreadBlocking configuration option type definition
packages/javascript/package.json	Bumped minor version from 3.2.18 to 3.3.0 for new feature
packages/javascript/README.md	Added documentation for main-thread blocking detection feature with configuration examples

Comments suppressed due to low confidence (2)

packages/javascript/src/addons/longTasks.ts:182

Using buffered: true means the observer will immediately process all past long task entries that occurred before the observer was set up. If Hawk is initialized late in the page lifecycle on a slow device, this could result in a burst of events being sent all at once, potentially overwhelming the transport or causing rate limiting issues. Consider documenting this behavior or providing an option to disable buffering for users who only want to track tasks from the point of initialization forward.

    }).observe({ type: 'longtask', buffered: true });

packages/javascript/src/addons/longTasks.ts:245

Using buffered: true means the observer will immediately process all past LoAF entries that occurred before the observer was set up. If Hawk is initialized late in the page lifecycle on a slow device, this could result in a burst of events being sent all at once, potentially overwhelming the transport or causing rate limiting issues. Consider documenting this behavior or providing an option to disable buffering for users who only want to track frames from the point of initialization forward.

    }).observe({ type: 'long-animation-frame', buffered: true });

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

neSpecc · 2026-02-23T21:25:21Z

+/**
+ * Build a Json object from entries, dropping null / undefined / empty-string values
+ */
+function compact(entries: [string, JsonNode | null | undefined][]): Json {


utility function should be added to /utils and covered by tests

…ThreadBlocking for clarity

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Co-authored-by: Peter <specc.dev@gmail.com>

…interfaces and improving script serialization

- Introduced `web-vitals` as a peer dependency and added it to the package.json. - Updated README to reflect new issues detection configuration, including `issues.webVitals`. - Refactored the catcher to utilize an `IssuesMonitor` for handling global errors and performance issues. - Removed the Long Tasks and LoAF tracking functionality, consolidating it under the new issues detection system.

Copilot

Pull request overview

Copilot reviewed 9 out of 10 changed files in this pull request and generated 5 comments.

Comments suppressed due to low confidence (10)

packages/javascript/src/addons/issues.ts:298

JSDoc comment is missing a description. It should describe what this function does, e.g., "Resolve and validate the threshold value, applying minimum and default values as needed."

/**
 *
 * @param value custom threshold
 * @param fallback default threshold
 */

packages/javascript/src/addons/issues.ts:319

JSDoc comment is missing a description. It should describe what this function does, e.g., "Serialize a LoAF script entry to a compact JSON object, omitting null and undefined values."

/**
 *
 * @param script loaf script entry
 */

packages/javascript/src/addons/issues.ts:338

JSDoc comment is missing a description. It should describe what this function does, e.g., "Serialize a Web Vitals report to a compact JSON object for transmission."

/**
 *
 * @param report aggregated vitals report
 */

packages/javascript/src/addons/issues.ts:81

JSDoc comment is missing a description. It should describe what this method does, e.g., "Observe Long Tasks using the Performance API and emit issues when duration exceeds threshold."

  /**
   *
   * @param thresholdMs max allowed duration
   * @param onIssue issue callback
   */

packages/javascript/src/addons/issues.ts:203

JSDoc comment is missing a description. It should describe what this method does, e.g., "Initialize Web Vitals monitoring and emit issue when at least one metric is poor."

  /**
   *
   * @param onIssue issue callback
   */

packages/javascript/src/addons/issues.ts:311

JSDoc comment is missing a description. It should describe what this function does, e.g., "Format a Web Vital metric value for display (fixed precision for CLS, milliseconds for others)."

/**
 *
 * @param name metric name
 * @param value metric value
 */

packages/javascript/src/addons/issues.ts:121

The observe call should have the options object on a single line or properly formatted. The current formatting with buffered: true on a separate line without proper indentation is inconsistent with typical JavaScript style conventions.

      this.longTaskObserver.observe({ type: 'longtask',
        buffered: true });

packages/javascript/src/addons/issues.ts:194

The observe call should have the options object on a single line or properly formatted. The current formatting with buffered: true on a separate line without proper indentation is inconsistent with typical JavaScript style conventions.

      this.loafObserver.observe({ type: 'long-animation-frame',
        buffered: true });

packages/javascript/src/addons/issues.ts:131

JSDoc comment is missing a description. It should describe what this method does, e.g., "Observe Long Animation Frames using the Performance API and emit issues when duration exceeds threshold."

  /**
   *
   * @param thresholdMs max allowed duration
   * @param onIssue issue callback
   */

packages/javascript/src/addons/issues.ts:281

JSDoc comment is missing a description. It should describe what this function does, e.g., "Check if the Performance API supports a specific entry type."

/**
 *
 * @param type performance entry type
 */

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-02-25T19:09:32Z

+      const tryReport = (): void => {
+        if (this.destroyed || reported || collected.length < TOTAL_WEB_VITALS) {
+          return;
+        }


The Web Vitals reporting waits for all 5 metrics (LCP, FCP, TTFB, INP, CLS) to be collected before reporting. However, not all metrics may be available on every page (e.g., INP requires user interaction, LCP may not occur on certain pages). This means poor metrics might never be reported if the page doesn't trigger all 5 metrics. Consider reporting when a timeout expires or when the page is about to be unloaded, rather than waiting for all 5 metrics indefinitely.

neSpecc · 2026-02-27T16:20:05Z

+  CLS: [0.1, 0.25],
+};
+
+const TOTAL_WEB_VITALS = 5;


its unclear for me. Describe the use case in jsdoc

neSpecc

All new features should be enabled out of the box by default

…tion and improved context details

…k and LoAF handling, including new attribution filters and structured addons

…ured addons and improved validation for long tasks and animation frames

neSpecc · 2026-04-27T16:50:13Z


-All detectors are enabled by default.
-If the browser does not support a specific Performance API (`longtask`, `long-animation-frame`), the corresponding detector is silently skipped.
+Default `issues` (when you omit the option or pass `{}`) is opt-in for performance detectors; global error listeners stay on:


make more straigtforward

neSpecc · 2026-04-27T16:53:08Z

 - 🛡️ Sensitive data filtering
 - 🌟 Source maps consuming
 - 💬 Console logs tracking
+- 🧊 Main-thread blocking detection (Long Tasks + LoAF, Chromium-only)


Suggested change

- 🧊 Main-thread blocking detection (Long Tasks + LoAF, Chromium-only)

- 🧊 Performance issues detection (Long Tasks + Long Animation Frames)

neSpecc · 2026-04-27T16:53:15Z

 - 💬 Console logs tracking
+- 🧊 Main-thread blocking detection (Long Tasks + LoAF, Chromium-only)
+- 📊 Web Vitals issues monitoring
+- ⚙️ Unified `issues` configuration (errors + performance detectors)


Suggested change

- ⚙️ Unified `issues` configuration (errors + performance detectors)

neSpecc · 2026-04-27T17:00:47Z

+Pass `true` or an options object for any detector you want. If the browser does not support a specific Performance API (`longtask`, `long-animation-frame`), the corresponding detector is silently skipped.
+
+Performance data is transmitted in the event **addons** (keys: `Long Task`, `Long Animation Frame`, `Web Vitals`).
+


Add Warning block:

It is highly recommended to specify a Grouping Pattern in your Project Settings to merge all "Long Task: ..." under a single Even to prevent overloading of event list

and pattern example

Long Task.+ Long Animation Frame.+

neSpecc · 2026-04-27T17:01:30Z

+    this.isInitialized = true;
+    this.destroyed = false;


one of them seems redundant.

find the reason how init can be called several times?

neSpecc · 2026-04-27T17:05:47Z

+ *
+ * @param entries
+ */
+export function compactJson(entries: [string, JsonNode | null | undefined][]): Json {


consider using Sanitizer.sanitize()

neSpecc · 2026-04-27T17:06:24Z

+  /**
+   * Issues monitor instance
+   */
+  private readonly issuesMonitor = new PerformanceIssuesMonitor();


maybe we dont need to call PerformanceIssuesMonitor if it is not enabled

neSpecc · 2026-04-27T17:07:20Z

+    }
+
+    if (shouldDetectPerformanceIssues) {
+      this.issuesMonitor.init(issues, (entry) => {


seems like it can't be initied several times, is isInitialized is probably redundant

neSpecc · 2026-04-27T17:07:40Z

…issues behavior

…h a single isActive flag for improved clarity and maintainability.

…with a new sanitizeIssuePayload function for improved data sanitization. Remove obsolete compactJson utility and its associated tests.

…ce readability

Dobrunia added 3 commits February 23, 2026 20:20

feat: add main-thread blocking detection (Long Tasks + LoAF)

f5a369f

chore: add JSDoc comments

db69d93

feat: enhance Long Tasks and LoAF handling with detailed attribution …

442da72

…and serialization

neSpecc requested a review from Copilot February 23, 2026 18:29

Copilot started reviewing on behalf of neSpecc February 23, 2026 18:30 View session

Copilot AI reviewed Feb 23, 2026

View reviewed changes

neSpecc reviewed Feb 23, 2026

View reviewed changes

Dobrunia and others added 8 commits February 24, 2026 00:59

refactor: update context structure in Long Tasks and LoAF to use main…

3381039

…ThreadBlocking for clarity

Update packages/javascript/src/addons/longTasks.ts

0eef530

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update packages/javascript/src/addons/longTasks.ts

fa6cb0f

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update packages/javascript/src/addons/longTasks.ts

54a6fd3

Co-authored-by: Peter <specc.dev@gmail.com>

Update packages/javascript/src/addons/longTasks.ts

203f1b7

Co-authored-by: Peter <specc.dev@gmail.com>

refactor: streamline Long Tasks and LoAF handling by removing unused …

068db0b

…interfaces and improving script serialization

refactor: update web-vitals handling and improve documentation.

b4755a1

Dobrunia requested a review from neSpecc February 25, 2026 18:44

neSpecc requested a review from Copilot February 25, 2026 19:00

Copilot started reviewing on behalf of neSpecc February 25, 2026 19:00 View session

Copilot AI reviewed Feb 25, 2026

View reviewed changes

Dobrunia changed the title ~~feat: add main-thread blocking detection (Long Tasks + LoAF)~~ feat: add main-thread blocking detection (Long Tasks + LoAF + web Vitals) Feb 26, 2026

Dobrunia added 2 commits February 26, 2026 05:39

chore: tests

d905d8b

fix: readme & tests

6ec3d83

neSpecc reviewed Feb 27, 2026

View reviewed changes

fix: naming

2619d36

neSpecc reviewed Feb 28, 2026

View reviewed changes

Comment thread packages/javascript/src/addons/performance-issues.ts Outdated

neSpecc reviewed Feb 28, 2026

View reviewed changes

Comment thread packages/javascript/src/addons/performance-issues.ts Outdated

Comment thread packages/javascript/src/types/issues.ts

Comment thread packages/javascript/README.md Outdated

Dobrunia added 2 commits March 2, 2026 16:00

chore: JSDoc

2906466

chore: cdn support

d77424c

neSpecc reviewed Mar 2, 2026

View reviewed changes

Comment thread packages/javascript/README.md Outdated

neSpecc approved these changes Mar 2, 2026

View reviewed changes

neSpecc requested changes Mar 3, 2026

View reviewed changes

neSpecc reviewed Mar 3, 2026

View reviewed changes

Comment thread packages/javascript/src/addons/performance-issues.ts Outdated

Dobrunia and others added 18 commits March 4, 2026 13:41

fix: update Web Vitals handling and improve documentation

15c2982

simplify readme

6f1d2cc

Update README.md

cdcb316

chore: update web-vitals dependency and improve performance monitoring

2d5f4ca

refactor: enhance performance issue monitoring with long task attribu…

a6a2a4d

…tion and improved context details

chore

d4ea672

refactor: improve performance issue monitoring with enhanced long tas…

5824ad7

…k and LoAF handling, including new attribution filters and structured addons

refactor: enhance README and performance issue monitoring with struct…

62adf6f

…ured addons and improved validation for long tasks and animation frames

chore

029115a

chore

5a206b4

chore

35ee372

navigationType

a61ec38

chore: add web vitals metric labels

2117a70

getWebVitalRatingThresholds

6d56404

Merge branch 'master' into feat/thread-blocking-detection

da281ae

fix

b8c1310

lint fix

ec425bd

Default settings updated

b4fff54

Dobrunia requested a review from neSpecc April 24, 2026 18:02

neSpecc reviewed Apr 27, 2026

View reviewed changes

Dobrunia added 4 commits April 27, 2026 20:28

Update README.md to clarify performance issues detection and default …

c9e89e3

…issues behavior

Refactor PerformanceIssuesMonitor to replace initialization flags wit…

367b7e0

…h a single isActive flag for improved clarity and maintainability.

Refactor performance issue payload handling by replacing compactJson …

f7f9f01

…with a new sanitizeIssuePayload function for improved data sanitization. Remove obsolete compactJson utility and its associated tests.

Update README.md formatting for default issues configuration to enhan…

d812192

…ce readability

Dobrunia requested a review from neSpecc April 27, 2026 17:54

	- 🧊 Main-thread blocking detection (Long Tasks + LoAF, Chromium-only)
	- 🧊 Performance issues detection (Long Tasks + Long Animation Frames)

		Pass `true` or an options object for any detector you want. If the browser does not support a specific Performance API (`longtask`, `long-animation-frame`), the corresponding detector is silently skipped.

		Performance data is transmitted in the event addons (keys: `Long Task`, `Long Animation Frame`, `Web Vitals`).

Conversation

Dobrunia commented Feb 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Defaults

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

neSpecc left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

Dobrunia commented Feb 23, 2026 •

edited

Loading