5.2 Log Rotation Service ¶

All these services produce many log files; they’re useful, for sure, but wouldn’t it be nice to archive them or even delete them periodically? The log rotation service does exactly that. Once you’ve enabled it, it periodically rotates the log files of services—those specified via the #:log-file argument of service constructors (see Service De- and Constructors)—those of the system log (see System Log Service), and also, optionally, “external” log files produced by some other mechanism.

By “rotating” we mean this: if a service produces /var/log/my-service.log, then rotating it consists in periodically renaming it and compressing it to obtain, say, /var/log/my-service.log.1.gz—after renaming the previous my-service.1.log.gz to my-service.log.2.gz, and so on⁵. Files older than some configured threshold are deleted instead of being renamed. The process is race-free: if the service is running, not a single line that it logs is lost during rotation.

To enable the log rotation service, you can add the following lines to your configuration file (see Service Examples):

(use-modules (shepherd service log-rotation))

(register-services
  ;; Create a service that rotates log files once a week.
  (list (log-rotation-service)))

;; Start it.
(start-service (lookup-service 'log-rotation))

This creates a log-rotation service, which is in fact a timed service (see Timers). By default it rotates logs once a week and you can see past and upcoming runs in the usual way:

herd status log-rotation

You can also trigger it explicitly at any time, like so:

herd trigger log-rotation

Last, you can list log files subject to rotation:

herd files log-rotation

The default settings should be good for most use cases, but you can change them by passing the log-rotation-service procedure a number of arguments—see the reference documentation below.

Procedure: log-rotation-service [event] [#:provision ’(log-rotation)] [#:requirement ’()] [#:external-log-files ’()] [#:compression (%default-log-compression)] [#:expiry (%default-log-expiry)] [#:rotation-size-threshold (%default-rotation-size-threshold)] ¶

Return a timed service that rotates service logs along with external-log-files (a list of file names such as /var/log/nginx/access.log corresponding to “external” log files not passed as #:log-file to any service) on every occurrence of event, a calendar event.

Compress log files according to method, which can be one of 'gzip, 'zstd, 'none, or a one-argument procedure that is passed the file name. Log files smaller than rotation-size-threshold are not rotated; copies older than expiry seconds are deleted.

Last, provision and requirement are lists of symbols specifying what the service provides and requires, respectively. Specifying requirement is useful to ensure, for example, that log rotation runs only if the service that mounts the file system that hosts log files is up.