[FEATURE] Implement simple log rotation

TYPO3 logs tend to grow over time if not manually cleaned on a regular
basis, potentially leading to full disks. Also, reading its contents
may be hard when several weeks of log entries are printed as a wall of
text.

To circumvent such issues, established tools like `logrotate` are
available for a long time already. However, TYPO3 may be installed on a
hosting environment where `logrotate` is not available and cannot be
installed by the customer. To cover such cases, a simple log rotation
approach is implemented.

A new file writer `\TYPO3\CMS\Core\Log\Writer\RotatingFileWriter` is
added that extends the already existing `FileWriter` class. The
`RotatingFileWriter` accepts two options:

The interval how often log files should be rotated can be configured
with any case of `\TYPO3\CMS\Core\Log\Writer\Enum\Interval`,
`Interval::DAILY` is the default. It's also possible to configure how
many log files are retained, where `5` is the default.

Resolves: #100926
Releases: main
Change-Id: Ibd60f9991cd9cc64e389c5bd4fd9aace25ea0e5e
Reviewed-on: https://review.typo3.org/c/Packages/TYPO3.CMS/+/79146
Tested-by: Susi Moog <look@susi.dev>
Tested-by: core-ci <typo3@b13.com>
Tested-by: Jochen Roth <rothjochen@gmail.com>
Reviewed-by: Jochen Roth <rothjochen@gmail.com>
Reviewed-by: Susi Moog <look@susi.dev>
Tested-by: Andreas Fernandez <a.fernandez@scripting-base.de>
Reviewed-by: Andreas Fernandez <a.fernandez@scripting-base.de>

typo3/sysext/core/Classes/Log/Writer/Enum/Interval.php

@@ -0,0 +1,36 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the TYPO3 CMS project.
+ *
+ * It is free software; you can redistribute it and/or modify it under
+ * the terms of the GNU General Public License, either version 2
+ * of the License, or any later version.
+ *
+ * For the full copyright and license information, please read the
+ * LICENSE.txt file that was distributed with this source code.
+ *
+ * The TYPO3 project - inspiring people to share!
+ */
+
+namespace TYPO3\CMS\Core\Log\Writer\Enum;
+
+enum Interval: string
+{
+    case DAILY = 'daily';
+    case WEEKLY = 'weekly';
+    case MONTHLY = 'monthly';
+    case YEARLY = 'yearly';
+
+    public function getDateInterval(): string
+    {
+        return match ($this) {
+            self::DAILY => 'P1D',
+            self::WEEKLY => 'P1W',
+            self::MONTHLY => 'P1M',
+            self::YEARLY => 'P1Y',
+        };
+    }
+}

typo3/sysext/core/Classes/Log/Writer/RotatingFileWriter.php

@@ -0,0 +1,168 @@
+<?php
+
+declare(strict_types=1);
+
+/*
+ * This file is part of the TYPO3 CMS project.
+ *
+ * It is free software; you can redistribute it and/or modify it under
+ * the terms of the GNU General Public License, either version 2
+ * of the License, or any later version.
+ *
+ * For the full copyright and license information, please read the
+ * LICENSE.txt file that was distributed with this source code.
+ *
+ * The TYPO3 project - inspiring people to share!
+ */
+
+namespace TYPO3\CMS\Core\Log\Writer;
+
+use TYPO3\CMS\Core\Locking\Exception\LockAcquireException;
+use TYPO3\CMS\Core\Locking\Exception\LockAcquireWouldBlockException;
+use TYPO3\CMS\Core\Locking\Exception\LockCreateException;
+use TYPO3\CMS\Core\Locking\LockFactory;
+use TYPO3\CMS\Core\Log\LogRecord;
+use TYPO3\CMS\Core\Log\Writer\Enum\Interval;
+use TYPO3\CMS\Core\Utility\GeneralUtility;
+
+/**
+ * Write logs into files while providing basic rotation capabilities. This is a very basic approach, suitable for
+ * environments where established tools like logrotate are not available.
+ */
+class RotatingFileWriter extends FileWriter
+{
+    private const ROTATION_DATE_FORMAT = 'YmdHis';
+
+    private Interval $interval = Interval::DAILY;
+    private int $maxFiles = 5;
+    private \DateTimeImmutable $lastRotation;
+    private \DateTimeImmutable $nextRotation;
+
+    public function __construct(array $options = [])
+    {
+        parent::__construct($options);
+    }
+
+    public function setLogFile(string $relativeLogFile): self
+    {
+        parent::setLogFile($relativeLogFile);
+
+        $this->updateRuntimeRotationState($this->getLastRotation());
+
+        return $this;
+    }
+
+    /**
+     * Internal setter called by FileWriter constructor
+     */
+    protected function setInterval(string|Interval $interval): void
+    {
+        if (is_string($interval)) {
+            // String support is required for use in system/settings.php
+            $this->interval = Interval::tryFrom($interval) ?? Interval::DAILY;
+        } else {
+            $this->interval = $interval;
+        }
+    }
+
+    /**
+     * Internal setter called by FileWriter constructor
+     */
+    protected function setMaxFiles(int $maxFiles): void
+    {
+        $this->maxFiles = max(0, $maxFiles);
+    }
+
+    public function writeLog(LogRecord $record)
+    {
+        if ($this->needsRotation()) {
+            $lockFactory = GeneralUtility::makeInstance(LockFactory::class);
+            try {
+                $lock = $lockFactory->createLocker('rotate-' . $this->logFile);
+                if ($lock->acquire()) {
+                    $this->updateRuntimeRotationState($this->getLastRotation());
+                    // check again if rotation is still needed (could have happened in the meantime)
+                    if ($this->needsRotation()) {
+                        $this->rotate();
+                    }
+                }
+                $lock->release();
+            } catch (LockCreateException|LockAcquireException|LockAcquireWouldBlockException) {
+            }
+        }
+        return parent::writeLog($record);
+    }
+
+    /**
+     * This method rotates all log files found by using `glob()` to take all already rotated logs into account, even
+     * after a configuration change.
+     *
+     * Log files are rotated using the "copytruncate" approach: the current open log file is copied as-is to a new
+     * location, the current log file gets flushed afterward. This way, file handles don't need to get re-created.
+     */
+    protected function rotate(): void
+    {
+        $rotationSuffix = date(self::ROTATION_DATE_FORMAT);
+
+        // copytruncate: Rotate the currently used log file
+        copy($this->logFile, $this->logFile . '.' . $rotationSuffix);
+        ftruncate(self::$logFileHandles[$this->logFile], 0);
+
+        $rotatedLogFiles = glob($this->logFile . '.*');
+        rsort($rotatedLogFiles, SORT_NATURAL);
+
+        // Remove any excess files
+        $excessFiles = array_slice($rotatedLogFiles, $this->maxFiles);
+        foreach ($excessFiles as $excessFile) {
+            unlink($excessFile);
+        }
+
+        $this->updateRuntimeRotationState(new \DateTimeImmutable());
+    }
+
+    protected function getLastRotation(): \DateTimeImmutable
+    {
+        // Rotate already rotated files again
+        $rotatedLogFiles = glob($this->logFile . '.*');
+
+        if ($rotatedLogFiles !== []) {
+            // Sort rotated files to handle the newest one first
+            rsort($rotatedLogFiles, SORT_NATURAL);
+            $newestLog = current($rotatedLogFiles);
+
+            $rotationDelimiterPosition = strrpos($newestLog, '.');
+            $timestamp = substr($newestLog, $rotationDelimiterPosition + 1);
+
+            $latestRotationDateTime = \DateTimeImmutable::createFromFormat(self::ROTATION_DATE_FORMAT, $timestamp);
+            if ($latestRotationDateTime instanceof \DateTimeImmutable) {
+                return $latestRotationDateTime;
+            }
+        }
+
+        return new \DateTimeImmutable('@0');
+    }
+
+    protected function determineNextRotation(): \DateTimeImmutable
+    {
+        return $this->lastRotation->add(new \DateInterval($this->interval->getDateInterval()));
+    }
+
+    /**
+     * Check if log files need to be rotated under following conditions:
+     *
+     * 1.
+     *    a) either the next rotation is due
+     *    b) logs were never rotated before
+     * 2. the log file is not empty - FileWriter::setLogFile() creates one if missing
+     */
+    protected function needsRotation(): bool
+    {
+        return ($this->nextRotation <= new \DateTimeImmutable() || $this->lastRotation->getTimestamp() === 0) && filesize($this->logFile) > 0;
+    }
+
+    protected function updateRuntimeRotationState(\DateTimeImmutable $lastRotation): void
+    {
+        $this->lastRotation = $lastRotation;
+        $this->nextRotation = $this->determineNextRotation();
+    }
+}

typo3/sysext/core/Documentation/Changelog/13.0/Feature-100926-IntroduceRotatingFileWriterforLogRotation.rst

@@ -0,0 +1,98 @@
+.. include:: /Includes.rst.txt
+
+.. _feature-100926-1685267155:
+
+=================================================================
+Feature: #100926 - Introduce `RotatingFileWriter`for log rotation
+=================================================================
+
+See :issue:`100926`
+
+Description
+===========
+
+TYPO3 logs tend to grow over time if not manually cleaned on a regular basis,
+potentially leading to full disks. Also, reading its contents may be hard when
+several weeks of log entries are printed as a wall of text.
+
+To circumvent such issues, established tools like `logrotate` are available for
+a long time already. However, TYPO3 may be installed on a hosting environment
+where `logrotate` is not available and cannot be installed by the customer.
+To cover such cases, a simple log rotation approach is implemented, following
+the "copytruncate" approach: when rotating files, the currently opened log file
+is copied (e.g. to `typo3_[hash].log.20230616094812`) and the original log file
+is emptied. This saves the hassle with properly closing and re-creating open
+file handles.
+
+A new file writer :php:`\TYPO3\CMS\Core\Log\Writer\RotatingFileWriter` is
+added that extends the already existing :php:`\TYPO3\CMS\Core\Log\Writer\FileWriter`
+class. The :php:`RotatingFileWriter` accepts all options of :php:`FileWriter` in
+addition of the following:
+
+* `interval` - how often logs should be rotated, can be any of
+  * :php:`daily` or :php:`\TYPO3\CMS\Core\Log\Writer\Enum\Interval::DAILY` (default)
+  * :php:`weekly` or :php:`\TYPO3\CMS\Core\Log\Writer\Enum\Interval::WEEKLY`
+  * :php:`monthly` or :php:`\TYPO3\CMS\Core\Log\Writer\Enum\Interval::MONTHLY`
+  * :php:`yearly` or :php:`\TYPO3\CMS\Core\Log\Writer\Enum\Interval::YEARLY`
+* `maxFiles` - how many files should be retained (by default `5` files, `0` never deletes any file)
+
+The :php:`RotatingFileWriter` is configured like any other writer.
+
+..  note::
+    When configuring :php:`RotatingFileWriter` in :file:`system/settings.php`,
+    string representations of the :php:`Interval` cases  need to be used for
+    `interval`, otherwise it may break the Install Tool.
+
+Example
+-------
+
+The following example introduces log rotation for the "main" log file.
+
+..  code-block:: php
+    :caption: system/additional.php
+
+    $GLOBALS['TYPO3_CONF_VARS']['LOG']['TYPO3']['CMS']['Core']['Resource']['ResourceStorage']['writerConfiguration'][\Psr\Log\LogLevel::ERROR] = [
+        \TYPO3\CMS\Core\Log\Writer\RotatingFileWriter::class => [
+            'interval' => \TYPO3\CMS\Core\Log\Writer\Enum\Interval::DAILY,
+            'maxFiles' => 5,
+        ],
+        \TYPO3\CMS\Core\Log\Writer\DatabaseWriter::class => [], // this is part of the default configuration
+    ];
+
+The following example introduces log rotation for the "deprecation" log file.
+
+..  code-block:: php
+    :caption: system/additional.php
+
+    $GLOBALS['TYPO3_CONF_VARS']['LOG']['TYPO3']['CMS']['deprecations']['writerConfiguration'][\Psr\Log\LogLevel::NOTICE] = [
+        \TYPO3\CMS\Core\Log\Writer\RotatingFileWriter::class => [
+            'logFileInfix' => 'deprecations',
+            'interval' => \TYPO3\CMS\Core\Log\Writer\Enum\Interval::WEEKLY,
+            'maxFiles' => 4,
+            'disabled' => false,
+        ],
+        \TYPO3\CMS\Core\Log\Writer\DatabaseWriter::class => [], // this is part of the default configuration
+    ];
+
+Impact
+======
+
+When configured, log files may be rotated before writing a new log entry,
+depending on the configured interval, where :php:`Interval::DAILY` is the
+default. When rotating, the log files are suffixed with a rotation incrementor
+value.
+
+Example:
+..  code-block:: console
+    :caption: Directory listing of `var/log` with rotated logs
+    $ ls -1 var/log
+    typo3_[hash].log
+    typo3_[hash].log.20230613065902
+    typo3_[hash].log.20230614084723
+    typo3_[hash].log.20230615084756
+    typo3_[hash].log.20230616094812
+
+If :php:`maxFiles` is configured with a value greater than `0`, any exceeding
+log file is removed.
+
+.. index:: LocalConfiguration, ext:core