feat(agent): add config option to not instrument framework exception handlers (#1113)

Our instrumentation of framework exception handlers can result in
excess, unwanted error events being generated. Sometimes, these events
are plentiful and diverse enough that manual filtering through them with
our other error related INI options is too much effort. In cases like
that, this setting exists as an easy solution. Errors may still appear
on spans, but error events will, in general, not be created. This works
especially well when the customer inserts their own error handling logic
into the stack, so that they are able to call our API for certain,
specific errors that they wish to be error events.

Author: ZNeumann

agent/fw_cakephp.c

@@ -173,10 +173,12 @@ void nr_cakephp_enable(TSRMLS_D) {
   nr_php_wrap_user_function(
       NR_PSTR("Cake\\Controller\\Controller::invokeAction"),
       nr_cakephp_name_the_wt_4);
-  nr_php_wrap_user_function(
-      NR_PSTR(
-          "Cake\\Error\\Middleware\\ErrorHandlerMiddleware::handleException"),
-      nr_cakephp_error_handler_wrapper);
+  if (!NRINI(ignore_framework_error_exception_handler)) {
+    nr_php_wrap_user_function(
+        NR_PSTR(
+            "Cake\\Error\\Middleware\\ErrorHandlerMiddleware::handleException"),
+        nr_cakephp_error_handler_wrapper);
+  }
   nr_txn_suggest_package_supportability_metric(NRPRG(txn), PHP_PACKAGE_NAME,
                                                PHP_PACKAGE_VERSION_UNKNOWN);
 }

agent/fw_drupal8.c

@@ -898,14 +898,16 @@ void nr_drupal8_enable(TSRMLS_D) {
   /*
    * Log exceptions without further handling.
    */
-  nr_php_wrap_user_function(NR_PSTR("Drupal\\Core\\EventSubscriber\\ExceptionLoggingSubscriber::onException"),
-                            nr_drupal_exception);
+  if (!NRINI(ignore_framework_error_exception_handler)) {
+    nr_php_wrap_user_function(NR_PSTR("Drupal\\Core\\EventSubscriber\\ExceptionLoggingSubscriber::onException"),
+                              nr_drupal_exception);
 
-  /*
-   * Last-chance handler for exceptions: the final exception subscriber.
-   */
-  nr_php_wrap_user_function(NR_PSTR("Drupal\\Core\\EventSubscriber\\FinalExceptionSubscriber::onException"),
-                            nr_drupal_exception);
+    /*
+     * Last-chance handler for exceptions: the final exception subscriber.
+     */
+    nr_php_wrap_user_function(NR_PSTR("Drupal\\Core\\EventSubscriber\\FinalExceptionSubscriber::onException"),
+                              nr_drupal_exception);
+  }
   // clang-format on
 
   /*

agent/fw_laravel.c

@@ -865,19 +865,21 @@ NR_PHP_WRAPPER(nr_laravel5_application_boot) {
    * to sensibly name transactions when an exception is thrown during routing
    * and also to record the error.
    */
-  exception_handler = nr_php_call_offsetGet(
-      this_var, "Illuminate\\Contracts\\Debug\\ExceptionHandler" TSRMLS_CC);
-  if (nr_php_is_zval_valid_object(exception_handler)) {
-    nr_laravel_add_callback_method(Z_OBJCE_P(exception_handler),
-                                   NR_PSTR("render"),
-                                   nr_laravel5_exception_render TSRMLS_CC);
-
-    nr_laravel_add_callback_method(Z_OBJCE_P(exception_handler),
-                                   NR_PSTR("report"),
-                                   nr_laravel5_exception_report TSRMLS_CC);
-  } else {
-    nrl_verbosedebug(NRL_FRAMEWORK, "%s: cannot get exception handler",
-                     __func__);
+  if (!NRINI(ignore_framework_error_exception_handler)) {
+    exception_handler = nr_php_call_offsetGet(
+        this_var, "Illuminate\\Contracts\\Debug\\ExceptionHandler" TSRMLS_CC);
+    if (nr_php_is_zval_valid_object(exception_handler)) {
+      nr_laravel_add_callback_method(Z_OBJCE_P(exception_handler),
+                                     NR_PSTR("render"),
+                                     nr_laravel5_exception_render TSRMLS_CC);
+
+      nr_laravel_add_callback_method(Z_OBJCE_P(exception_handler),
+                                     NR_PSTR("report"),
+                                     nr_laravel5_exception_report TSRMLS_CC);
+    } else {
+      nrl_verbosedebug(NRL_FRAMEWORK, "%s: cannot get exception handler",
+                       __func__);
+    }
   }
 
 end:

agent/fw_lumen.c

@@ -218,16 +218,18 @@ void nr_lumen_enable(TSRMLS_D) {
   nr_php_wrap_user_function(
       NR_PSTR("Laravel\\Lumen\\Application::handleFoundRoute"),
       nr_lumen_handle_found_route TSRMLS_CC);
+  if (!NRINI(ignore_framework_error_exception_handler)) {
 #if ZEND_MODULE_API_NO >= ZEND_8_0_X_API_NO \
     && !defined OVERWRITE_ZEND_EXECUTE_DATA
-  nr_php_wrap_user_function_before_after_clean(
-      NR_PSTR("Laravel\\Lumen\\Application::sendExceptionToHandler"),
-      nr_lumen_exception, NULL, NULL);
+    nr_php_wrap_user_function_before_after_clean(
+        NR_PSTR("Laravel\\Lumen\\Application::sendExceptionToHandler"),
+        nr_lumen_exception, NULL, NULL);
 #else
-  nr_php_wrap_user_function(
-      NR_PSTR("Laravel\\Lumen\\Application::sendExceptionToHandler"),
-      nr_lumen_exception TSRMLS_CC);
+    nr_php_wrap_user_function(
+        NR_PSTR("Laravel\\Lumen\\Application::sendExceptionToHandler"),
+        nr_lumen_exception TSRMLS_CC);
 #endif
+  }
 
   if (NRINI(vulnerability_management_package_detection_enabled)) {
     nr_txn_add_php_package(NRPRG(txn), PHP_PACKAGE_NAME,

agent/fw_symfony4.c

@@ -250,19 +250,21 @@ void nr_symfony4_enable(TSRMLS_D) {
    * nr_txn_record_error and pass the exception message. Now we get errors in
    * the error analytics page.
    */
-  nr_php_wrap_user_function(
-      NR_PSTR("Symfony\\Component\\HttpKernel\\"
-              "EventListener\\ExceptionListener::onKernelException"),
-      nr_symfony4_exception TSRMLS_CC);
+  if (!NRINI(ignore_framework_error_exception_handler)) {
+    nr_php_wrap_user_function(
+        NR_PSTR("Symfony\\Component\\HttpKernel\\"
+                "EventListener\\ExceptionListener::onKernelException"),
+        nr_symfony4_exception TSRMLS_CC);
 
-  /*
-   * In Symfony 5 listener that catch errors was changed to ErrorListener,
-   * we try to hook into it
-   */
-  nr_php_wrap_user_function(
-      NR_PSTR("Symfony\\Component\\HttpKernel\\"
-              "EventListener\\ErrorListener::onKernelException"),
-      nr_symfony4_exception TSRMLS_CC);
+    /*
+     * In Symfony 5 listener that catch errors was changed to ErrorListener,
+     * we try to hook into it
+     */
+    nr_php_wrap_user_function(
+        NR_PSTR("Symfony\\Component\\HttpKernel\\"
+                "EventListener\\ErrorListener::onKernelException"),
+        nr_symfony4_exception TSRMLS_CC);
+  }
 
   /*
    * Listen for Symfony commands so we can name those appropriately.

agent/fw_yii.c

@@ -219,8 +219,10 @@ void nr_yii2_enable(TSRMLS_D) {
    * allowing default PHP error handler to be intercepted by the NewRelic agent
    * implementation.
    */
-  nr_php_wrap_user_function(NR_PSTR("yii\\base\\ErrorHandler::logException"),
-                            nr_yii2_error_handler_wrapper TSRMLS_CC);
+  if (!NRINI(ignore_framework_error_exception_handler)) {
+    nr_php_wrap_user_function(NR_PSTR("yii\\base\\ErrorHandler::logException"),
+                              nr_yii2_error_handler_wrapper TSRMLS_CC);
+  }
 #endif
 
   if (NRINI(vulnerability_management_package_detection_enabled)) {

agent/php_newrelic.h

@@ -238,6 +238,9 @@ nrinibool_t
 nrinibool_t
     ignore_user_exception_handler; /* newrelic.error_collector.ignore_user_exception_handler
                                     */
+nrinibool_t
+    ignore_framework_error_exception_handler; /* newrelic.error_collector.ignore_framework_error_excpetion_handler
+                                               */
 nriniint_t ignore_errors;     /* newrelic.error_collector.ignore_errors */
 nrinistr_t ignore_exceptions; /* newrelic.error_collector.ignore_exceptions */
 nrinibool_t

agent/php_nrini.c

@@ -2587,6 +2587,14 @@ STD_PHP_INI_ENTRY_EX("newrelic.error_collector.ignore_user_exception_handler",
                      zend_newrelic_globals,
                      newrelic_globals,
                      nr_yes_no_dh)
+STD_PHP_INI_ENTRY_EX("newrelic.error_collector.ignore_framework_error_exception_handler",
+                     "0",
+                     NR_PHP_REQUEST,
+                     nr_boolean_mh,
+                     ignore_framework_error_exception_handler,
+                     zend_newrelic_globals,
+                     newrelic_globals,
+                     nr_yes_no_dh)
 STD_PHP_INI_ENTRY_EX("newrelic.error_collector.ignore_errors",
                      "",
                      NR_PHP_REQUEST,

agent/scripts/newrelic.ini.template

@@ -432,6 +432,22 @@ newrelic.daemon.logfile = "/var/log/newrelic/newrelic-daemon.log"
 ;
 ;newrelic.error_collector.ignore_user_exception_handler = false
 
+; Setting: newrelic.error_collector.ignore_framework_error_exception_handler
+; Type   : boolean
+; Scope  : per-directory
+; Default: false
+; Info   : If enabled, the New Relic error collector will ignore any errors or
+;          exceptions that are handled by a framework error or exception
+;          handler.
+;
+;          This is useful if you only want to see exceptions that are re-
+;          thrown by the framework or if you are inserting your own
+;          handling logic into the exception handling stack that will
+;          filter errors/exceptions and manually call the New Relic API
+;          when instrumentation is desired.
+;
+;newrelic.error_collector.ignore_framework_error_exception_handler = false
+
 ; Setting: newrelic.error_collector.ignore_exceptions
 ; Type:    string
 ; Scope:   per-directory