logging and errors

introduction

dframework provides a dual channel logging system that writes to both the console and persistent log files. it includes an error handler that renders error pages, classifies stack traces by component type, maps compiled view errors back to their original template lines, and provides diagnostic tips for common mistakes.

the logger

log levels

the logger supports six log levels, each with its own color coding and behavior.

the minimum log level is determined by whether debug mode is enabled. when app.debug is true, all levels including debug are output. when debug is disabled, debug messages are suppressed.

writing log messages

each log level has a corresponding method accessible via the global Log facade. all methods accept variadic arguments that are automatically formatted.

1Log.debug('cache miss for key:', cacheKey);
2Log.info('user registered:', user.email);
3Log.warn('rate limit approaching for ip:', clientIp);
4Log.error('payment failed:', error);

the logger formats different argument types. strings are output as is, Error objects display their full stack trace, promises display as Promise { <pending> }, and objects are pretty printed with a depth of 3 and color support in the local environment.

table logging

the Log.table() method renders an array of objects as a formatted ascii table with box drawing characters.

1app.logger.table([
2  { name: 'users', rows: 1250, size: '2.4 MB' },
3  { name: 'posts', rows: 8340, size: '15.1 MB' },
4  { name: 'sessions', rows: 89, size: '0.1 MB' }
5], 'database overview');

1database overview
2┌─────────┬──────┬─────────┐
3│ name    │ rows │ size    │
4├─────────┼──────┼─────────┤
5│ users   │ 1250 │ 2.4 MB  │
6│ posts   │ 8340 │ 15.1 MB │
7│ sessions│ 89   │ 0.1 MB  │
8└─────────┴──────┴─────────┘

log output

console output

in the local environment, all log messages are output to the console with ansi color coding. error and warning messages use console.error to separate them from standard output.

in the production environment, colors are stripped and only warn and error messages go to console.error. all other levels use console.log.

file output

every log message is simultaneously written to a persistent log file. log files are stored in the logs directory at the root of your project, separated by environment.

1logs/
2├── dev/
3│   ├── dframework_2026-06-04.log
4│   └── dframework_2026-06-05.log
5└── prod/
6    ├── dframework_2026-06-04.log
7    └── dframework_2026-06-05.log

the local environment writes to logs/dev/ and production writes to logs/prod/. ansi color codes are automatically stripped from file output.

log file rotation

log files are automatically rotated daily. each file is named with the date (dframework_YYYY-MM-DD.log). when the date changes, the logger detects that the current file path no longer matches, closes the previous write stream, and opens a new one for the current date.

you can clear log files using the cli.

1dstrn logs:clear
2dstrn logs:clear --env=prod
3dstrn logs:clear --before=2026-01-01
4dstrn logs:clear --after=2026-05-01 --archive
5dstrn logs:clear --preview

debug bar integration

in the local environment with debug mode enabled, log messages are automatically captured by the request context and included in the debug bar response. each log entry records its level, message (with colors stripped), and timestamp. this allows you to see every log message that was generated during a specific request directly in the browser's debug panel.

configuration

the logger reads its configuration from the application config.

1// config/app.js
2export default {
3  env: 'local',
4  debug: true
5};

the error handler

the ErrorHandler class manages error rendering and logging throughout the application. it is instantiated during app boot and caches all error page templates for instant rendering.

error pages

dframework includes built in error pages for the following http status codes: 400, 401, 403, 404, 405, 419, 429, 500, 502, 503, and 504. each page uses the framework's view template syntax and displays a styled error screen to the user.

when an error occurs, the error handler selects the appropriate template based on the status code. if no template exists for the specific code, it falls back to the 500 template. if no templates are available at all, a plain text response is sent.

custom error pages

you can override any built in error page by placing a file with the same name in your views/errors directory. user error pages take priority over the framework defaults.

1views/errors/
2├── 404.d
3├── 500.d
4└── 503.d

your custom error pages have access to the {{ status }} placeholder which is replaced with the numeric status code.

debug error page

when app.debug is true and the error is not a 404, the framework renders a detailed debug error page instead of the production error page. the debug page displays:

• the http status code
• the error message
• the classified stack trace with component level color coding

this page is designed for development only and is never shown in the production environment.

error tips

the error handler includes a pattern matching system that recognizes common error messages and provides diagnostic tips. when an error is logged, the handler checks the message against a list of known patterns.

tips are displayed in cyan below the error message in the console output.

1[Socket] Template rendering failed: Cannot read properties of undefined (reading 'name')
2tip: verify object exists before accessing properties
3  ▸ [controller]   UserController                  controllers/UserController.js:42
4  ▸ [view]         home                            views/home.d:15

stack trace classification

the error handler transforms raw stack traces into classified, color coded frames that highlight the most relevant parts of the trace.

frame categories

each stack frame is classified into a category based on its file path.

frames from node_modules and the framework's core directory are automatically filtered out. only your application code is shown in the trace.

1  ▸ [controller]   register                        controllers/AuthController.js:28
2  ▸ [model]        create                          models/User.js:15
3  ▸ [view]         auth.register                   views/auth/register.d:42

view line mapping

when an error originates from a compiled view template, the error handler maps the compiled javascript line number back to the original line in the .d template file. this is done using the line map generated during view compilation, ensuring that the stack trace points to the exact line in your template that caused the error rather than the generated code.

hot reload path resolution

in the local environment, the framework uses cache busted file paths (.hot-*) for hot reloading. the error handler resolves these back to the original file paths in the stack trace, so you always see clean, recognizable paths.