Debugging, logging and errors
This page is for developers who rely on a profiler toolbar and a PSR-3 logger. Exponential has its own debug output, turned into a pinned debug bar, its own logging calls, and an administration page that reads the logs (Debugging and logs).
Contents
- Debug output and the debug bar
- Writing debug and log lines
- The log files
- From an error page to the log line
- Debugging under Velocity
- Compared with other frameworks
Debug output and the debug bar
# settings/override/site.ini.append.php, or the dev variant of it (development only)
[DebugSettings]
DebugOutput=enabled
[TemplateSettings]
ShowTemplatePathComments=enabledThe debug bar shows queries, templates used, settings, timings and caches for the page, and has controls for the debug
settings and the caches (Exp debug bar). It can be shown to your own address only.
Template path comments print which file wrote which markup (Template path comments).
Never enable debug output on a production siteaccess for everyone; it shows internals. Put it in the dev variant of
your settings (Environments and secrets).
Writing debug and log lines
eZDebug::writeNotice( 'Imported 12 items', __METHOD__ );
eZDebug::writeWarning( 'Item 42 had no title', __METHOD__ );
eZDebug::writeError( 'Feed could not be read: ' . $message, __METHOD__ );
eZLog::write( 'archive sent for object ' . (int)$objectID, 'expdemo.log' );Warnings and errors go to var/log/warning.log and var/log/error.log whatever the debug setting; eZLog::write()
writes a log of your own in the log directory. These are not PSR-3 loggers; if you use Monolog in your extension, it
writes its own files. Never log passwords, keys, tokens or personal data.
The log files
| File | Holds |
|---|---|
var/log/error.log, warning.log | errors and warnings |
var/log/security.log | security events |
var/log/csp.log | Content Security Policy reports |
var/log/requestrules.log | the log action of request rules |
your own *.log | what your code writes |
Setup > Logs shows them with a digest of repeated messages (Log viewer); logs rotate (Log rotation); request logs record requests with timings (Request logs). Security-relevant actions belong in the audit trail (Audit trail). In a multisite installation the log paths can differ per site (Multi-site log and cache paths).
From an error page to the log line
Error pages carry a reference; search the logs for it to find the full message (Finding an error by its reference). The first page for any problem is When something goes wrong.
Debugging under Velocity
- Workers keep classes and settings in memory: after a change,
./console exp:velocity deploy(orrestart), or you are debugging old code. - Compare with PHP's built-in server engine (
--engine=php), which runs each request fresh, when you suspect state kept between requests (Velocity engines). - Never wrap
eZExecution::cleanExit()incatch ( Exception $e ): under Velocity it ends the request with an exception.
Compared with other frameworks
| Framework | Tool | Exponential |
|---|---|---|
| Symfony | web profiler, Monolog | debug bar, eZDebug, eZLog, Setup > Logs |
| Laravel | Debugbar, Telescope, Log:: | the same |
| Django | Debug Toolbar, logging | the same |
| Rails | logs, byebug | the same; Xdebug works as in any PHP project |
| Spring | Actuator, SLF4J | Setup > System information, request logs |
Related pages
- Debug bar guide
- Debug output improvements
- Template errors and debugging
- Free documentation: this page is free to copy, translate and improve under the GNU FDL 1.3.
Become an Exponential Partner
Partners share their information, provide funding, contribute back and develop the products with us, and that is how Exponential grows. A partner website and dashboard are planned for mid-2027: please become a partner today to speed up our growth rate and land new features faster.