DOC Update error handling and logging docs (#660)

en/02_Developer_Guides/07_Debugging/01_Error_Handling.md

@@ -6,7 +6,7 @@ icon: exclamation-circle
 
 # Logging and error handling
 
-Silverstripe CMS uses Monolog for both error handling and logging. It comes with two default configurations: one for
+Silverstripe CMS uses Monolog for both error handling (for PHP errors and uncaught exceptions) and logging. It comes with two default configurations: one for
 logging, and another for core error handling. The core error handling implementation also comes with two default
 configurations: one for development environments, and another for test or live environments. On development
 environments, Silverstripe CMS will deal harshly with any warnings or errors: a full call-stack is shown and execution
@@ -196,7 +196,15 @@ SilverStripe\Core\Injector\Injector:
 
 The `info` argument provides the minimum level to start logging at.
 
-### Disabling the default handler
+### Modifying the default error handler
+
+The default error handler catches uncaught exceptions and PHP errors and displays them in the browser and terminal.
+
+> [!WARNING]
+> In general you should not attach your own error handler to the `Psr\Log\LoggerInterface.errorhandler` error handler service.
+> Attaching a your handler to the `Psr\Log\LoggerInterface` service will allow you to handle unchaught exceptions, PHP errors, and manually logged error messages, and is therefore preferred.
+
+#### Disabling the default error handler
 
 You can disable a handler by removing its pushHandlers call from the calls option of the Logger service definition.
 The handler key of the default handler is `pushDisplayErrorHandler`, so you can disable it like this:
@@ -208,7 +216,7 @@ SilverStripe\Core\Injector\Injector:
       pushDisplayErrorHandler: '%%remove%%'
 ```
 
-### Setting a different configuration for dev
+#### Setting a different configuration for dev
 
 In order to set different logging configuration on different environment types, we rely on the environment-specific
 configuration features that the config system providers. For example, here we have different configuration for dev and

en/06_Upgrading/07_Deprecations.md

@@ -53,7 +53,7 @@ By default, deprecation warnings will be emitted to the error logger, and will b
 
 ### Viewing deprecation warnings in the logs
 
-Deprecation warnings are output to the same error logger as all other warnings and errors. You will need to make sure you have a logging handler attached to the default `Psr\Log\LoggerInterface` or `Psr\Log\LoggerInterface.errorhandler` singletons. For example, to log to a file you can add this to your YAML configuration:
+Deprecation warnings are output to the same error logger as all other warnings and errors. You will need to make sure you have a logging handler attached to the default `Psr\Log\LoggerInterface` singleton. For example, to log to a file you can add this to your YAML configuration:
 
 ```yml
 SilverStripe\Core\Injector\Injector:
@@ -62,7 +62,7 @@ SilverStripe\Core\Injector\Injector:
     constructor:
       - "/var/www/silverstripe.log"
       - "warning" # warning is the level deprecation warnings are logged as
-  Psr\Log\LoggerInterface.errorhandler:
+  Psr\Log\LoggerInterface:
     calls:
       ErrorLogFileHandler: [ pushHandler, [ '%$ErrorLogFileHandler' ] ]
 ```

en/08_Changelogs/5.4.0.md

@@ -262,6 +262,16 @@ The `SilverStripe\CMS\Model\SiteTree.DESCRIPTION` localisation key (along with t
 
 This release includes a number of bug fixes to improve a broad range of areas. Check the change logs for full details of these fixes split by module. Thank you to the community members that helped contribute these fixes as part of the release!
 
+### Change to error logging
+
+Some errors were incorrectly being logged using the error handler service, which resulted in displaying the error in the browser and CLI and, in live mode, not displaying the rest of the response to users.
+
+This was the result of a misunderstanding about the difference between the `Psr\Log\LoggerInterface.errorhandler` error handler service and the `Psr\Log\LoggerInterface` logging service.
+
+The `Psr\Log\LoggerInterface.errorhandler` error handler service should *not* be used for logging - its purpose is to handle the display of uncaught exceptions and PHP errors.
+
+Errors that were being logged to the error handler service are now being logged using the logging service instead. If you have connected a logging handler to that service, we recommend instead following the instructions in [configuring error logging](/developer_guides/debugging/error_handling/#configuring-error-logging) to attach your logging handler *only* to the logging service, which will also allow you to handle logging for the uncaught exceptions and errors the error handler displays.
+
 <!--- Changes below this line will be automatically regenerated -->
 
 <!--- Changes above this line will be automatically regenerated -->