Gruxi Web Server

Appearance

Logging ​

Logging is an important aspect of running and maintaining a web server. Gruxi provides several logging options to help you monitor and troubleshoot your server.

INFO

Gruxi does logging in a performance-conscious way. Request handling is always prioritized over logging, so logging will never slow down request processing. This means that in high-load situations, some log entries may be dropped to ensure optimal performance. Slow disk I/O or full disks may also lead to lost log entries. But this is a conscious trade-off to ensure that the server remains responsive under load.

System logging ​

By default, Gruxi logs very little about requests unless errors occur.

Gruxi writes a gruxi.log file under /logs, which includes startup messages and any errors that occur.

A task ID is included in the log entries, which can be used to correlate log entries with specific requests or tasks. For example, you might see log entries like this (the task ID is shown in square brackets after the log level, for example [ID:39]):

2026-02-06T09:12:08.083554Z - [TRACE][ID:39] [FileCacheUpdate] Checking if we are above the eviction threshold, so we can delete files in cache that have been in cache for too long
2026-02-06T09:12:08.083578Z - [TRACE][ID:39] [FileCacheUpdate] Cache size is below eviction threshold - No delete action taken
2026-02-06T09:12:08.083580Z - [TRACE][ID:39] [FileCacheUpdate] Checking for modified timestamps and if known files still exist
2026-02-06T09:12:08.083622Z - [TRACE][ID:39] [FileCacheUpdate] Files found to check for modified timestamps: 7

Access logging ​

You can enable access logging per site. When enabled, each request made to that site is written to the log location configured on the site.

Trace logging - detailed logging ​

For development or bug tracking purposes, trace logging can be enabled to provide more detailed logs.

This is done by running Gruxi with the -o DEV option or setting the operation mode to DEV in the admin portal.

bash
gruxi -o DEV

This generates a lot of log output, which can be useful for debugging but will also impact performance significantly. Only enable this when needed, and disable it again when you are done troubleshooting.

Log rotation ​

Gruxi implements log rotation to manage log file size and age. This prevents log files from growing indefinitely and consuming too much disk space. Many web servers choose not to handle log rotation themselves and instead rely on external tools like logrotate to manage log files. However, Gruxi includes built-in log rotation functionality to simplify log management for users.

Log rotation is triggered when a log file reaches a certain size or time, at which point the current log file is archived and a new log file is created.

The log rotation functionality supports these options:

  • Global enable/disable: Whether log rotation is enabled or not
  • Rotate By Size enable/disable: Whether log rotation should be triggered based on file size
    • size: The file size threshold (in megabytes) that triggers log rotation when the log file exceeds this size
  • Rotate By Time enable/disable: Whether log rotation should be triggered based on file time/age
    • interval: The interval, defined as daily, weekly, or monthly, that triggers log rotation when the log file reaches this age
  • Delete old log files enable/disable: Whether old log files should be automatically deleted after a certain period
    • days: The age threshold (in days) for deleting old log files when the "Delete old log files" option is enabled

When log rotation is triggered, the current log file is renamed with a timestamp and a new log file is created to continue logging. This helps to keep log files manageable and prevents them from consuming too much disk space over time.

Example log file names after rotation might look like this:

  • gruxi.log (current log file)
  • gruxi.20260205.142427.rotated.log (rotated log file with timestamp)

INFO

Only files with .log extension in the ./logs directory are rotated. So if you have access log files with a different extension, they will not be rotated by Gruxi's built-in log rotation functionality. You would need to use an external tool like logrotate to manage those log files if you want to implement log rotation for them.