Skip to content

Commit 64f4a59

Browse files
linawolfsarahmccarthy123
linawolf
and
sarahmccarthy123
authored
[TASK] Add production logging configuration guide (#5758)
* [TASK] Add production logging configuration guide Add new chapter on configuring TYPO3 logging for production environments Covers log levels, rotation, deprecation log disabling, centralized error monitoring (e.g., Sentry), and system log management tools Clarify separation between developer-focused logging API and production usage; add cross-links between related chapters for better navigation Backport to 12.4 would have to be done manually due to the introduction of the rotatinglogwriter with v13.0 Releases: main, 13.4 * [TASK] Add production logging configuration guide Add new chapter on configuring TYPO3 logging for production environments Covers log levels, rotation, deprecation log disabling, centralized error monitoring (e.g., Sentry), and system log management tools Clarify separation between developer-focused logging API and production usage; add cross-links between related chapters for better navigation Backport to 12.4 would have to be done manually due to the introduction of the rotatinglogwriter with v13.0 Releases: main, 13.4 * [TASK] Language checks Releases: main * Update Documentation/Administration/Production/Logging/Index.rst * Apply suggestions from code review * [TASK] Update code snippets Releases: main --------- Co-authored-by: Sarah McCarthy <[email protected]>
1 parent 1ae87bf commit 64f4a59

File tree

10 files changed

+349
-39
lines changed

10 files changed

+349
-39
lines changed

‎Documentation/Administration/Production/Index.rst‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,12 +36,21 @@ running TYPO3 for production.
3636

3737
* `Backup strategy <https://docs.typo3.org/permalink/t3coreapi:administration-backups>`_
3838

39+
.. card:: Configure production logging
40+
41+
Learn how to properly configure TYPO3 logging for production systems.
42+
Covers log levels, rotation, system tools, error monitoring services
43+
(e.g., Sentry), and security best practices.
44+
45+
* `Logging in production <https://docs.typo3.org/permalink/t3coreapi:production-logging>`_
46+
3947
.. toctree::
4048
:titlesonly:
4149
:hidden:
4250

4351
Backups/Index
4452
Security/Index
53+
Logging/Index
4554
ReverseProxy/Index
4655
OPcache/Index
4756

‎Documentation/Administration/Production/Logging/Index.rst‎

Lines changed: 218 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,218 @@
1+
:navigation-title: Logging
2+
3+
.. include:: /Includes.rst.txt
4+
.. _production-logging:
5+
6+
========================================
7+
Logging considerations during production
8+
========================================
9+
10+
In production environments, improperly configured logging can lead to issues
11+
such as bloated log files, degraded performance, and even website outages due
12+
to full disk space.
13+
14+
TYPO3 has several configuration options and tools to keep log files
15+
manageable, secure, and relevant. This guide covers practical strategies for
16+
controlling log volume, reducing noise, and monitoring critical events.
17+
18+
.. seealso::
19+
20+
For an overview of how logging works inside TYPO3 and how to use it in
21+
custom code or extensions, see the :ref:`logging` chapter in the API section.
22+
23+
.. warning::
24+
25+
Log files can grow rapidly in production and may eventually exhaust
26+
available disk space, causing TYPO3 to become unresponsive or inaccessible.
27+
28+
.. contents:: Table of contents
29+
30+
.. _production-logging-level:
31+
32+
Limit the level to be logged
33+
============================
34+
35+
Each log entry in TYPO3 is associated with a severity level. For details on
36+
log levels, refer to the TYPO3 documentation:
37+
`Log levels <https://docs.typo3.org/permalink/t3coreapi:logging-logger-shortcuts>`_.
38+
39+
During development, it is often useful to log detailed information. In
40+
production, logging should be limited to important issues—typically messages at
41+
the `ERROR` level or higher—to reduce disk usage and improve performance.
42+
43+
By default, when the
44+
`Application Context <https://docs.typo3.org/permalink/t3coreapi:application-context>`_
45+
is set to `Production`, only messages with a severity of
46+
:php-short:`\Psr\Log\LogLevel::ERROR` or higher are logged.
47+
48+
You can also configure different writers for specific log levels. This allows
49+
you to, for example, write warnings and errors to separate files, or ignore
50+
lower-severity messages altogether.
51+
52+
The following example demonstrates how to configure log writers per log
53+
level:
54+
55+
.. literalinclude:: _codesnippets/_loglevels.php
56+
:caption: config/system/additional.php | typo3conf/system/additional.php
57+
58+
.. _production-logging-monitor:
59+
60+
Monitor the log and address common log entries
61+
==============================================
62+
63+
Some log messages may appear frequently without indicating a critical or
64+
harmful issue. For example, an outdated
65+
`TypoScript condition <https://docs.typo3.org/permalink/t3tsref:typoscript-syntax-conditions-examples>`_
66+
written in legacy syntax can trigger log entries every time TypoScript is
67+
evaluated for a page.
68+
69+
Fixing such recurring issues helps reduce the size of your log files and
70+
improves the overall quality and maintainability of your code base.
71+
72+
.. _production-logging-rotation:
73+
74+
Use log rotation
75+
================
76+
77+
.. versionadded:: 13.0
78+
79+
Replace :php-short:`\TYPO3\CMS\Core\Log\Writer\FileWriter`
80+
with :php-short:`\TYPO3\CMS\Core\Log\Writer\RotatingFileWriter`. Define a
81+
rotation interval and specify how many rotated files should be retained.
82+
83+
.. seealso::
84+
85+
* `RotatingFileWriter configuration <https://docs.typo3.org/permalink/t3coreapi:logging-writers-rotatingfilewriter>`_
86+
87+
The following example adds log rotation for the "main" log file:
88+
89+
.. literalinclude:: /ApiOverview/Logging/Writers/_additionalRotationFileWriter.php
90+
:caption: config/system/additional.php | typo3conf/system/additional.php
91+
92+
If you are using extensions such as
93+
:composer:`apache-solr-for-typo3/solr` that configure custom log files,
94+
you also need to switch those log files to use the
95+
:php-short:`\TYPO3\CMS\Core\Log\Writer\RotatingFileWriter`.
96+
97+
.. _production-logging-system-tools:
98+
99+
Use system-Level log management tools
100+
=====================================
101+
102+
In addition to TYPO3's internal logging features, it is common practice to
103+
use server-level tools to manage log files. These tools can rotate, archive,
104+
compress, and delete log files based on size, age, or other criteria.
105+
106+
On Linux systems, consider using the following tools:
107+
108+
* **logrotate** – A standard utility for automatic log rotation, commonly
109+
pre-installed on most Linux distributions. It can be configured to manage
110+
TYPO3 logs and system logs.
111+
112+
* **systemd-journald** – If your server uses systemd, you can use
113+
journald for logging, with configurable rotation and retention.
114+
115+
* **cron jobs with custom scripts** – For more specific needs, administrators
116+
can use scheduled scripts to archive or delete logs periodically.
117+
118+
.. tip::
119+
120+
If using `logrotate`, ensure the log directory (e.g.,
121+
:file:`var/log/`) is included in the configuration, and set appropriate
122+
permissions so the rotation process can access the files.
123+
124+
.. _production-logging-centralized:
125+
126+
Use centralized error monitoring (e.g., Sentry)
127+
===============================================
128+
129+
In many production environments, it is common to offload error tracking to a
130+
centralized service like `Sentry <https://sentry.io>`_. These tools
131+
capture unhandled exceptions and application errors with full context,
132+
including stack traces, request details, and environment variables.
133+
134+
Sentry can often **replace the need for local error log management**,
135+
especially when it is used as the main tool for observing application behavior
136+
and alerting failures. However, local logs may still be useful for storing
137+
lower-level messages, audit trails, or when dealing with infrastructure-related
138+
issues.
139+
140+
TYPO3 supports Sentry integration via third-party extensions such as:
141+
142+
* :composer:`networkteam/sentry-client` (A Sentry client for TYPO3)
143+
144+
.. tip::
145+
146+
Sentry is best suited for tracking uncaught exceptions and user-facing
147+
errors. It is not designed to store full application logs such as debug
148+
output or access logs.
149+
150+
.. _deprecation-disable-errors:
151+
152+
Disabling the deprecation log on production
153+
===========================================
154+
155+
By default, when the
156+
`Application Context <https://docs.typo3.org/permalink/t3coreapi:application-context>`_
157+
is set to `Production`, the deprecation log is disabled.
158+
159+
Check the log directory, for example :path:`/path/to/project/var/log` and ensure
160+
no logfile has been written with `deprecation` in the name.
161+
162+
As best practice you should only configure
163+
deprecation logs for `Development` contexts, for example:
164+
165+
.. literalinclude:: /ApiOverview/Deprecation/_additional.php
166+
:caption: config/system/additional.php | typo3conf/system/additional.php
167+
168+
If the deprecation log is still being written in production,
169+
you can explicitly disable it by unsetting its configuration:
170+
171+
.. literalinclude:: _codesnippets/_disableDeprecationLog.php
172+
:caption: config/system/additional.php | typo3conf/system/additional.php
173+
174+
If the deprecation log continues to be written, check the following:
175+
176+
#. **Verify the Application Context**
177+
178+
The current context (e.g., `Production`) is shown in the top bar of the TYPO3
179+
backend under the :guilabel:`System Information` module.
180+
181+
#. **Check the resolved configuration**
182+
183+
Use the :guilabel:`System > Configuration` module (requires
184+
:composer:`typo3/cms-lowlevel`) to inspect the effective value of
185+
`$GLOBALS['TYPO3_CONF_VARS']['LOG']['TYPO3']['CMS']['deprecations']`.
186+
187+
#. **Look for overrides in extensions**
188+
189+
Some extensions may override logging settings in their
190+
:file:`ext_localconf.php` or :file:`ext_tables.php`. Check these files
191+
if your configuration appears to be ignored.
192+
193+
.. _production-logging-security:
194+
195+
Securing TYPO3 logs in production
196+
=================================
197+
198+
TYPO3 logs may contain sensitive information that could be exploited by an
199+
attacker to gain information about your system. Logs may also include personal
200+
data such as IP addresses, which must be handled with care to ensure
201+
privacy compliance.
202+
203+
**In Composer-based TYPO3 installations**, logs are written to
204+
:path:`/path/to/project/var/log` by default. Since this directory is
205+
located *outside* the web server’s document root
206+
(:path:`/path/to/project/public`), it cannot be accessed directly from the
207+
internet—providing a level of built-in security.
208+
209+
**In Classic-mode TYPO3 installations**, logs are stored in
210+
:path:`/path/to/project/typo3conf/var/log`. Because the document root in
211+
Classic mode typically points to :path:`/path/to/project`, this log
212+
directory is publicly accessible by default. **Additional precautions must
213+
be taken** to prevent unauthorized access.
214+
215+
.. seealso::
216+
217+
* `Secure file permissions (operating system level) <https://docs.typo3.org/permalink/t3coreapi:security-file-directory-permissions>`_
218+
* `Restrict HTTP access <https://docs.typo3.org/permalink/t3coreapi:security-restrict-access-server-level>`_ (for Classic mode)

‎Documentation/Administration/Production/Logging/_codesnippets/_disableDeprecationLog.php‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,12 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
use TYPO3\CMS\Core\Core\Environment;
6+
7+
// Add this at the very bottom of your system/additional.php
8+
// Or your site packages ext_localconf.php to override settings
9+
// made by other extensions
10+
if (Environment::getContext()->isProduction()) {
11+
unset($GLOBALS['TYPO3_CONF_VARS']['LOG']['TYPO3']['CMS']['deprecations']);
12+
}

‎Documentation/Administration/Production/Logging/_codesnippets/_loglevels.php‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
<?php
2+
3+
declare(strict_types=1);
4+
5+
use Psr\Log\LogLevel;
6+
use TYPO3\CMS\Core\Log\Writer\Enum\Interval;
7+
use TYPO3\CMS\Core\Log\Writer\NullWriter;
8+
use TYPO3\CMS\Core\Log\Writer\RotatingFileWriter;
9+
10+
$GLOBALS['TYPO3_CONF_VARS']['LOG']['writerConfiguration'] = [
11+
LogLevel::WARNING => [
12+
// Explicitly disable warning level logs
13+
NullWriter::class => [],
14+
],
15+
LogLevel::ERROR => [
16+
// Keep error level logs for a week
17+
RotatingFileWriter::class => [
18+
'interval' => Interval::DAILY,
19+
'maxFiles' => 7,
20+
],
21+
],
22+
LogLevel::CRITICAL => [
23+
// Keep critical level logs for eight weeks
24+
RotatingFileWriter::class => [
25+
'interval' => Interval::WEEKLY,
26+
'maxFiles' => 8,
27+
],
28+
],
29+
];

‎Documentation/ApiOverview/Deprecation/Index.rst‎

Lines changed: 29 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,49 +1,47 @@
1-
.. include:: /Includes.rst.txt
2-
.. index:: ! Deprecation
3-
.. _deprecation:
4-
5-
===========
6-
Deprecation
7-
===========
1+
:navigation-title: Deprecation Handling
82

9-
.. contents::
10-
:local:
11-
12-
.. index:: Deprecation; Log
3+
.. include:: /Includes.rst.txt
134
.. _deprecation_introduction:
145
.. _cgl-deprecation:
6+
.. _deprecation:
157

16-
Introduction
17-
============
8+
===============================================================
9+
Deprecation handling: logging, marking and finding deprecations
10+
===============================================================
1811

19-
Calls to deprecated functions are logged to track usage of deprecated/outdated
20-
methods in the TYPO3 Core. Developers have to make sure to adjust their code to
21-
avoid using this old functionality since deprecated methods will be removed in
22-
future TYPO3 releases.
12+
TYPO3 logs calls to deprecated functions to help developers identify and update
13+
outdated code. Deprecated methods will be removed in future TYPO3 versions, so
14+
they should be avoided.
2315

24-
Deprecations use the PHP method :php:`trigger_error('a message', E_USER_DEPRECATED)`
25-
and run through the logging and exception stack of the TYPO3 Core. There are
26-
several methods that help extension developers in dispatching deprecation
27-
errors. In the development context, deprecations are turned into exceptions by
28-
default and ignored in the production context.
16+
Deprecations are triggered by :php:`trigger_error()` and pass through TYPO3’s
17+
logging and exception system. In development, they are shown as exceptions by
18+
default; in production, they are typically ignored.
2919

3020
.. note::
3121
For information how to handle deprecations in the TYPO3 Core,
3222
see the Contribution Guide: :ref:`t3contribute:deprecations`.
3323

24+
.. contents:: Table of content
25+
:local:
3426

3527
.. index:: Deprecation; Log enabling
36-
.. _deprecation_disable_errors:
37-
.. _deprecation_enable_errors:
28+
.. _deprecation-enable-errors:
3829

39-
Enabling deprecation errors
40-
===========================
30+
Enabling the deprecation log
31+
============================
4132

42-
TYPO3 ships with a default configuration, in which deprecation logging is
33+
TYPO3 ships with a default configuration where deprecation logging is
4334
**disabled**. If you upgrade to the latest TYPO3 version, you need to change
44-
your development configuration to enable deprecation logging in case you need
35+
your development configuration to enable deprecation logging if you need
4536
it.
4637

38+
.. seealso::
39+
40+
To learn how to properly disable the deprecation log in production, see
41+
:ref:`deprecation-disable-errors`.
42+
43+
.. _deprecation-enable-errors-gui:
44+
4745
Via GUI
4846
-------
4947

@@ -60,14 +58,16 @@ selecting the :guilabel:`Live` preset instead.
6058

6159
Enabling the debug preset
6260

63-
The debug preset enables also some other debug settings.
61+
The debug preset also enables some other debug settings.
6462

6563
.. note::
6664
These steps only enable/disable the :ref:`FileWriter <logging-writers-FileWriter>`,
6765
which comes with the TYPO3 default configuration. If you manually configured
6866
**additional** writers for the `TYPO3.CMS.deprecations` logger, you need to
6967
manually remove them to completely disable deprecation logging.
7068

69+
.. _deprecation-enable-errors-config:
70+
7171
Via configuration file directly
7272
-------------------------------
7373

‎Documentation/ApiOverview/Logging/Configuration/Index.rst‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
:navigation-title: Configuration
2+
13
.. include:: /Includes.rst.txt
24
.. index:: pair: Logging; Configuration
35
.. _logging-configuration:
@@ -13,6 +15,13 @@ The logger configuration is read from :php:`$GLOBALS['TYPO3_CONF_VARS']['LOG']`,
1315
which contains an array reflecting the namespace and class hierarchy of your
1416
TYPO3 project.
1517

18+
.. seealso::
19+
20+
Are you configuring logging for a live TYPO3 instance?
21+
See :ref:`production-logging` for best practices on logging in production
22+
environments, including log rotation, log levels, file storage, and
23+
monitoring tools like Sentry.
24+
1625
For example, to apply a configuration for all loggers within the
1726
:php:`\TYPO3\CMS\Core\Cache` namespace, the configuration is read from
1827
:php:`$GLOBALS['TYPO3_CONF_VARS']['LOG']['TYPO3']['CMS']['Core']['Cache']`.

0 commit comments

Comments
 (0)