-
Notifications
You must be signed in to change notification settings - Fork 4
feat: add main-thread blocking detection (Long Tasks + LoAF + web Vitals) #166
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
Dobrunia
wants to merge
38
commits into
master
Choose a base branch
from
feat/thread-blocking-detection
base: master
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from 11 commits
Commits
Show all changes
38 commits
Select commit
Hold shift + click to select a range
f5a369f
feat: add main-thread blocking detection (Long Tasks + LoAF)
Dobrunia db69d93
chore: add JSDoc comments
Dobrunia 442da72
feat: enhance Long Tasks and LoAF handling with detailed attribution …
Dobrunia 3381039
refactor: update context structure in Long Tasks and LoAF to use main…
Dobrunia 0eef530
Update packages/javascript/src/addons/longTasks.ts
Dobrunia fa6cb0f
Update packages/javascript/src/addons/longTasks.ts
Dobrunia 54a6fd3
Update packages/javascript/src/addons/longTasks.ts
Dobrunia 203f1b7
Update packages/javascript/src/addons/longTasks.ts
Dobrunia 068db0b
refactor: streamline Long Tasks and LoAF handling by removing unused …
Dobrunia 7355dda
feat: add web-vitals support and refactor issues handling
Dobrunia b4755a1
refactor: update web-vitals handling and improve documentation.
Dobrunia d905d8b
chore: tests
Dobrunia 6ec3d83
fix: readme & tests
Dobrunia 2619d36
fix: naming
Dobrunia 2906466
chore: JSDoc
Dobrunia d77424c
chore: cdn support
Dobrunia 15c2982
fix: update Web Vitals handling and improve documentation
Dobrunia 6f1d2cc
simplify readme
neSpecc cdcb316
Update README.md
neSpecc 2d5f4ca
chore: update web-vitals dependency and improve performance monitoring
Dobrunia a6a2a4d
refactor: enhance performance issue monitoring with long task attribu…
Dobrunia d4ea672
chore
Dobrunia 5824ad7
refactor: improve performance issue monitoring with enhanced long tas…
Dobrunia 62adf6f
refactor: enhance README and performance issue monitoring with struct…
Dobrunia 029115a
chore
Dobrunia 5a206b4
chore
Dobrunia 35ee372
chore
Dobrunia a61ec38
navigationType
Dobrunia 2117a70
chore: add web vitals metric labels
Dobrunia 6d56404
getWebVitalRatingThresholds
Dobrunia da281ae
Merge branch 'master' into feat/thread-blocking-detection
Dobrunia b8c1310
fix
Dobrunia ec425bd
lint fix
Dobrunia b4fff54
Default settings updated
Dobrunia c9e89e3
Update README.md to clarify performance issues detection and default …
Dobrunia 367b7e0
Refactor PerformanceIssuesMonitor to replace initialization flags wit…
Dobrunia f7f9f01
Refactor performance issue payload handling by replacing compactJson …
Dobrunia d812192
Update README.md formatting for default issues configuration to enhan…
Dobrunia File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -11,6 +11,7 @@ Error tracking for JavaScript/TypeScript applications. | |
| - 🛡️ Sensitive data filtering | ||
| - 🌟 Source maps consuming | ||
| - 💬 Console logs tracking | ||
| - 🧊 Main-thread blocking detection (Chromium-only) | ||
| - <img src="https://cdn.svglogos.dev/logos/vue.svg" width="16" height="16"> Vue support | ||
| - <img src="https://cdn.svglogos.dev/logos/react.svg" width="16" height="16"> React support | ||
|
|
||
|
|
@@ -85,11 +86,12 @@ Initialization settings: | |
| | `user` | {id: string, name?: string, image?: string, url?: string} | optional | Current authenticated user | | ||
| | `context` | object | optional | Any data you want to pass with every message. Has limitation of length. | | ||
| | `vue` | Vue constructor | optional | Pass Vue constructor to set up the [Vue integration](#integrate-to-vue-application) | | ||
| | `disableGlobalErrorsHandling` | boolean | optional | Do not initialize global errors handling | | ||
| | `disableGlobalErrorsHandling` | boolean | optional | Deprecated. Use `issues.errors: false` instead. | | ||
| | `disableVueErrorHandler` | boolean | optional | Do not initialize Vue errors handling | | ||
| | `consoleTracking` | boolean | optional | Initialize console logs tracking | | ||
| | `breadcrumbs` | false or BreadcrumbsOptions object | optional | Configure breadcrumbs tracking (see below) | | ||
| | `beforeSend` | function(event) => event \| false \| void | optional | Filter data before sending. Return modified event, `false` to drop the event. | | ||
| | `issues` | IssuesOptions object | optional | Issues config: `errors`, `webVitals`, `longTasks.thresholdMs`, `longAnimationFrames.thresholdMs` | | ||
|
|
||
| Other available [initial settings](types/hawk-initial-settings.d.ts) are described at the type definition. | ||
|
|
||
|
|
@@ -232,6 +234,82 @@ const breadcrumbs = hawk.breadcrumbs.get(); | |
| hawk.breadcrumbs.clear(); | ||
| ``` | ||
|
|
||
| ## Issues Detection | ||
|
|
||
| `issues` is an umbrella option for problems detected by the catcher. | ||
| Browser support depends on the specific detector: | ||
| - `errors` — works in all supported browsers | ||
| - `webVitals` — via `web-vitals` package | ||
| - `longTasks` / `longAnimationFrames` — Chromium-only (`long-animation-frame` requires Chrome/Edge 123+) | ||
|
|
||
| It currently includes three groups: | ||
|
|
||
| - `issues.errors` — global runtime errors handling | ||
| - `issues.webVitals` — aggregated Core Web Vitals report | ||
| - `issues.longTasks` and `issues.longAnimationFrames` — freeze-related detectors | ||
|
|
||
| Freeze detectors use two complementary APIs: | ||
|
|
||
|
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Add
and pattern example |
||
| - **Long Tasks API** — reports any task taking longer than 50 ms. | ||
| - **Long Animation Frames (LoAF)** — reports frames taking longer than 50 ms with richer script attribution (Chrome 123+, Edge 123+). | ||
|
|
||
| Both freeze detectors are enabled by default. If one API is unsupported, the other still works. | ||
| Each detected freeze is reported immediately with detailed context (duration, blocking time, scripts involved, etc.). | ||
| `thresholdMs` is the max allowed duration budget. Hawk emits an issue when measured duration is equal to or greater than this value. Values below `50ms` are clamped to `50ms`. | ||
|
neSpecc marked this conversation as resolved.
Outdated
|
||
|
|
||
| ### Web Vitals (Aggregated) | ||
|
|
||
| When `issues.webVitals` is enabled, Hawk collects all Core Web Vitals (`LCP`, `FCP`, `TTFB`, `INP`, `CLS`) and sends a single issue event when at least one metric is rated `poor`. | ||
|
|
||
| The event context contains all metrics with: | ||
| - `value` | ||
| - `rating` | ||
| - `delta` | ||
|
|
||
| `web-vitals` is an optional peer dependency and is loaded only when `issues.webVitals: true`. | ||
|
|
||
| ### Disabling | ||
|
|
||
| Disable global errors handling: | ||
|
|
||
| ```js | ||
| const hawk = new HawkCatcher({ | ||
| token: 'INTEGRATION_TOKEN', | ||
| issues: { | ||
| errors: false | ||
| } | ||
| }); | ||
| ``` | ||
|
|
||
| ### Selective Configuration | ||
|
|
||
| Configure all issue detectors: | ||
|
|
||
| ```js | ||
| const hawk = new HawkCatcher({ | ||
| token: 'INTEGRATION_TOKEN', | ||
| issues: { | ||
| errors: true, | ||
| webVitals: true, | ||
| longTasks: { | ||
| thresholdMs: 100 | ||
| }, | ||
| longAnimationFrames: { | ||
| thresholdMs: 500 | ||
| } | ||
| } | ||
| }); | ||
| ``` | ||
|
|
||
| ### Options | ||
|
|
||
| | Option | Type | Default | Description | | ||
| |--------|------|---------|-------------| | ||
| | `errors` | `boolean` | `true` | Enable global errors handling (`window.onerror` and `unhandledrejection`). | | ||
| | `webVitals` | `boolean` | `false` | Collect all Core Web Vitals and send one issue event when at least one metric is rated `poor`. Requires optional `web-vitals` dependency. | | ||
| | `longTasks` | `false` or `{ thresholdMs?: number }` | `{ thresholdMs: 100 }` | Detect long tasks and emit issue events when duration is equal to or greater than the max allowed duration (`thresholdMs`, minimum effective value is `50ms`). | | ||
| | `longAnimationFrames` | `false` or `{ thresholdMs?: number }` | `{ thresholdMs: 500 }` | Detect LoAF events and emit issue events when duration is equal to or greater than the max allowed duration (`thresholdMs`, minimum effective value is `50ms`). Requires Chrome 123+ / Edge 123+. | | ||
|
|
||
| ## Source maps consuming | ||
|
|
||
| If your bundle is minified, it is useful to pass source-map files to the Hawk. After that you will see beautiful | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.