Report fatal errors potentially caused by Site Kit if opted in to event tracking
- Dominant language
- JavaScript
- Stars
- 1.4k
- Forks
- 384
- Avg merge
- 4d 14h
- Merged PRs (30d)
- 77
Description
In order to be aware of any fatal errors related to Site Kit that happen in the wild (e.g. to more quickly and proactively discover something like #3830 in the future), we should collect fatal errors for those Site Kit users that have opted in to tracking. This will bring parity with what we already have in JS, which has helped us identify and fix breaking JS errors in the wild.
Catching and recording PHP errors is slightly more complex, but in a way even more crucial than JS errors as in the worst case it can bring down the entire site.
---------------
_Do not alter or remove anything below. The following sections will be managed by moderators only._
## Acceptance criteria
* Site Kit should track PHP fatal errors in the following circumstances:
* The current user has opted into tracking.
* The fatal error has at least one Site Kit file in its stack trace.
* Every such fatal error should be sent to Analytics as follows:
* Event category: `php_error`
* Event name: _TBD_
* Event label: error message, followed by the list of file and line number pairs from the stack trace (in a comparable format to how `react_error` events are sent)
* In order to catch fatal errors, Site Kit should, as early as the plugin code is loaded, integrate with WordPress core's fatal error detection mechanism:
* It should use the [`wp_should_handle_php_error` filter](https://developer.wordpress.org/reference/hooks/wp_should_handle_php_error/) to get the error, passing through the filter value. The error should only be handled if WordPress considers it a fatal error (i.e. filter value is `true`) and if the above conditions are satisfied.
* _TBD_
## Implementation Brief
*
### Test Coverage
*
### Visual Regression Changes
*
## QA Brief
*
## Changelog entry
*
Contributor guide
Research direction
Start at the earliest plugin-loading entry point and review WordPress's wp_should_handle_php_error filter documentation. Trace how existing react_error events are sent to Analytics and determine how the PHP error and stack-trace data should correspond. Done means opted-in users' fatal errors involving a Site Kit file are handled only when WordPress marks them fatal and are sent with the specified category and label.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- php, wordpress
- Domain
- analytics, backend, observability
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100