Merge pull request #14221 from nextcloud/jtr/docs-admin-logging-chapter-v33plus

Author: skjnldsv

admin_manual/configuration_server/logging_configuration.rst

@@ -35,7 +35,7 @@ All log information will be sent to PHP ``error_log()``.
 
     "log_type" => "errorlog",
 
-.. warning:: Until Nextcloud 25, log entries were prefixed with ``[owncloud]``. From 26 onwards, log entries start with ``[nextcloud]``.
+Log entries will be prefixed with ``[nextcloud]``.
 
 file
 ~~~~
@@ -58,6 +58,82 @@ date format in the example below, the date/time format will be written in the fo
     "loglevel" => 3,
     "logdateformat" => "F d, Y H:i:s",
 
+Additional file-based logging parameters
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following optional parameters can also be set in :file:`config/config.php`:
+
+**logfilemode**
+    Sets the file permissions (in octal notation) for the log file.
+
+    Defaults to ``0640``.
+
+    ::
+
+        "logfilemode" => 0640,
+
+**logtimezone**
+    Sets the timezone used for log timestamps. See the `PHP list of supported timezones <https://www.php.net/manual/en/timezones.php>`_.
+
+    Defaults to ``UTC``.
+
+    ::
+
+        "logtimezone" => "Europe/Berlin",
+
+**log_rotate_size**
+    Enables log rotation and limits the total size of log files. The value is
+    specified in bytes. When the current log file reaches this size a new log
+    file is created. If a rotated log file already exists it will be
+    overwritten. Set to ``0`` to disable rotation.
+
+    Defaults to ``104857600`` (100 MB).
+
+    ::
+
+        "log_rotate_size" => 100 * 1024 * 1024,
+
+**log.backtrace**
+    When enabled, a backtrace is appended to every log line, not only to
+    exceptions. This significantly increases log size and should only be used
+    for debugging.
+
+    Defaults to ``false``.
+
+    ::
+
+        "log.backtrace" => true,
+
+**log_query**
+    Appends all database queries and their parameters to the log file. Use
+    this only for debugging as it produces very large log files.
+
+    Defaults to ``false``.
+
+    ::
+
+        "log_query" => true,
+
+**loglevel_frontend**
+    Sets a separate log level for messages originating from the Nextcloud
+    frontend (browser). Accepts the same values as ``loglevel`` (0–4).
+
+    Defaults to ``2`` (WARN).
+
+    ::
+
+        "loglevel_frontend" => 2,
+
+**loglevel_dirty_database_queries**
+    Sets the log level at which dirty database queries (queries executed
+    after the response has already been sent) are logged.
+
+    Defaults to ``0`` (DEBUG).
+
+    ::
+
+        "loglevel_dirty_database_queries" => 0,
+
 syslog
 ~~~~~~
 
@@ -80,6 +156,101 @@ All log information will be sent to Systemd journal. Requires `php-systemd <http
     "log_type" => "systemd",
     "syslog_tag" => "Nextcloud",
 
+Conditional logging (log.condition)
+-----------------------------------
+
+Nextcloud supports conditional overrides that temporarily increase the log
+level to **DEBUG** when certain criteria are met. This is useful for
+diagnosing problems in production without flooding the entire log with debug
+output.
+
+The ``log.condition`` parameter is set in :file:`config/config.php`.
+
+Basic conditions
+~~~~~~~~~~~~~~~~
+
+At the top level you can specify one or more of the following keys. When
+*any* of them match, the log level for that request is set to **DEBUG**:
+
+**shared_secret**
+    Match requests that pass the query parameter ``log_secret`` with this
+    value.
+
+**users**
+    An array of user IDs. If the currently authenticated user is in the
+    list, the condition is satisfied.
+
+**apps**
+    An array of app identifiers. Any log message whose app context matches
+    one of these apps will be logged at DEBUG level.
+
+Example – enable debug logging for user ``jane`` and the ``files`` app:
+
+::
+
+    'log.condition' => [
+        'users' => ['jane'],
+        'apps' => ['files'],
+    ],
+
+Advanced compound conditions (matches)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``matches`` key accepts an array of condition groups. Each group can
+combine all of the keys above plus:
+
+**message**
+    A substring that must appear in the log message.
+
+**loglevel**
+    The log level to apply when this group matches (instead of the default
+    DEBUG / ``0``).
+
+All keys within a single group must match for the group to apply (logical
+AND). Multiple groups are evaluated independently (logical OR).
+
+Example – log all messages from the ``files`` app at INFO level, and log any
+message containing ``"Lock"`` for user ``admin`` at DEBUG level:
+
+::
+
+    'log.condition' => [
+        'matches' => [
+            [
+                'apps' => ['files'],
+                'loglevel' => 1,
+            ],
+            [
+                'users' => ['admin'],
+                'message' => 'Lock',
+                'loglevel' => 0,
+            ],
+        ],
+    ],
+
+Using a shared secret for on-demand debugging
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can trigger debug logging for a single request by adding a
+``log_secret`` query parameter. Set a secret in :file:`config/config.php`:
+
+::
+
+    'log.condition' => [
+        'shared_secret' => '57b58edb6637fe3059b3595cf9c41b9',
+    ],
+
+Then call your Nextcloud URL with the secret appended:
+
+::
+
+    https://cloud.example.com/index.php?log_secret=57b58edb6637fe3059b3595cf9c41b9
+
+.. warning::
+
+    Keep the shared secret private. Anyone who knows it can enable debug-level
+    logging on your instance.
+
 Log fields explained
 --------------------
 
@@ -122,87 +293,155 @@ Log field breakdown
 * **reqId** (request id): any log lines related to a single request have the same value
 * **level**: logged incident's level, always 1 in audit.log
 * **time**: date and time (format and timezone can be configured in config.php)
-* **remoteAddr**: the IP address of the user (if applicable  – empty for occ commands)
+* **remoteAddr**: the IP address of the user (if applicable – empty for occ commands)
 * **user**: acting user's id (if applicable)
 * **app**: affected app (always admin_audit in audit.log)
-* **method**: HTTP method, for example GET, POST, PROPFIND, etc.  – empty on occ calls
+* **method**: HTTP method, for example GET, POST, PROPFIND, etc. – empty on occ calls
 * **url**: request path (if applicable – empty on occ calls)
+* **scriptName**: the PHP script name that handled the request
 * **message**: event information message
 * **userAgent**: user agent (if applicable – empty on occ calls)
-* **exception**: Full exception with trace (if applicable)
-* **data** additional structured data (if applicable)
+* **exception**: full exception with trace (if applicable)
+* **data**: additional structured data (if applicable)
 * **version**: Nextcloud version at the time of request
+* **clientReqId**: value of the ``X-Request-Id`` HTTP header sent by the client (only present when the header is set)
+* **occ_command**: the occ command that was executed, as an array of up to two arguments (only present in CLI mode)
+* **backtrace**: full PHP backtrace (only present when ``log.backtrace`` is enabled in config.php)
 
-Empty value are written as two dashes: ``--``.
+Empty values are written as two dashes: ``--``.
 
 Admin audit log (Optional)
 --------------------------
 
 .. _config-admin-audit:
 
-By enabling the **admin_audit** app, additional information about various events can be logged. Similar to the normal logging, the audit log can be provided to any of the existing logging mechanisms in :file:`config/config.php`. The default behavior, if no parameters are specified after the app is enabled, is ``file`` based logging to a file called ``audit.log`` stored in the ``datadirectory``.
+By enabling the **admin_audit** app, additional information about various
+events can be logged. The audit log supports all of the logging backends
+described above (file, syslog, systemd, errorlog).
+
+Default audit log location
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-If you wish to override this and log to syslog instead the following would be one approach:
+When using the default ``file`` backend, the audit log is written to
+**audit.log** inside the directory configured by ``datadirectory`` in
+:file:`config/config.php` (e.g. ``/var/www/html/data/audit.log``).
+
+You can override the path with the ``logfile_audit`` system config key:
+
+::
+
+    'logfile_audit' => '/var/log/nextcloud/audit.log',
+
+Dedicated audit logging configuration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The audit log backend can be configured independently from the main
+Nextcloud log using three dedicated keys in :file:`config/config.php`:
+
+**log_type_audit**
+    The logging backend for audit events. Accepts the same values as
+    ``log_type``: ``file``, ``syslog``, ``systemd``, or ``errorlog``.
+
+    Defaults to ``file``.
+
+**logfile_audit**
+    Path to the audit log file (only used when ``log_type_audit`` is
+    ``file``). When empty, the default ``audit.log`` in the data directory
+    is used.
+
+**syslog_tag_audit**
+    The syslog identifier for audit messages (only used when
+    ``log_type_audit`` is ``syslog`` or ``systemd``). Defaults to the value
+    of ``syslog_tag``.
+
+Example – send audit events to syslog instead of a file:
 
 ::
 
-	"log_type_audit" => "syslog",
-	"syslog_tag_audit" => "Nextcloud",
-	"logfile_audit" => "",
+    'log_type_audit' => 'syslog',
+    'syslog_tag_audit' => 'Nextcloud',
+    'logfile_audit' => '',
 
 Log level interaction
 ~~~~~~~~~~~~~~~~~~~~~
 
-If system ``loglevel`` in ``config.php`` is set to ``2`` or higher, audit logging needs to be triggered explicitly by adding the following setting to ``config.php``:
+The **admin_audit** app writes its messages at **INFO** level (``1``).
+Because the default system ``loglevel`` is **WARN** (``2``), audit messages
+are suppressed unless you explicitly lower the system log level or add a
+conditional override.
+
+The recommended approach is to add a ``log.condition`` entry that forces
+DEBUG-level logging for the ``admin_audit`` app context, without affecting
+other apps:
 
 ::
 
-	"log.condition" => [
-		"apps" => ["admin_audit"],
-	],
+    'log.condition' => [
+        'apps' => ['admin_audit'],
+    ],
 
-Find detailed documentation on auditable events for enterprises in our `customer portal <https://portal.nextcloud.com/article/using-the-audit-log-44.html>`_.
+This ensures audit events are always written regardless of the global
+``loglevel`` setting.
 
-Integrating into the Web Interface
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Integrating into the web interface
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The built-in NC ``logreader`` app (which is what provides the *Administration settings->Logging* interface) only accesses the file-based ``nextcloud.log``. The **admin_audit** app log output, however, can be integrated into the web interface by configuring it to *also* log to the ``nextcloud.log``.
+The built-in **logreader** app (which provides *Administration settings →
+Logging*) only reads the file-based ``nextcloud.log``. By default the
+audit log is written to a separate ``audit.log`` file, so audit entries
+will not appear in the web interface.
 
-Add the following to your ``config.php`` (adjusting the path to your own ``nextcloud.log`` path):
+If you want audit events to appear in the logreader, point
+``logfile_audit`` at the same file as ``nextcloud.log``:
 
 ::
 
-	'log.condition' => [
-		'apps' => [ 'admin_audit'],
-	],
-	'logfile_audit' => '/var/www/html/data/nextcloud.log',
+    'log.condition' => [
+        'apps' => ['admin_audit'],
+    ],
+    'logfile_audit' => '/var/www/html/data/nextcloud.log',
 
-Configuring through admin_audit app settings
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+.. note::
 
-Previously the audit logfile was defined in the app config. This config is still used when the system config is not provided, but is considered a legacy parameter.
+    Adjust the path above to match your actual ``datadirectory`` location.
+    This merges audit entries into the main log file; the separate
+    ``audit.log`` will no longer be written.
 
-::
+Configuring through admin_audit app settings (legacy)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-	occ config:app:set admin_audit logfile --value=/var/log/nextcloud/audit.log
+Previously the audit log file was defined via app config. This setting is
+still read as a fallback when ``logfile_audit`` is not set in
+:file:`config/config.php`, but it is considered a **legacy** parameter.
+The system config key should be preferred for new installations.
 
-.. _PHP date function: http://www.php.net/manual/en/function.date.php
+::
+
+    occ config:app:set admin_audit logfile --value=/var/log/nextcloud/audit.log
 
 Workflow log
 ------------
 
-By default, the workflow log is stored to `flow.log` in the data folder.
+The **workflowengine** app records events related to Nextcloud Flow
+(automated workflows configured under *Administration settings → Flow*).
+By default, these events are written to ``flow.log`` inside the data
+directory.
 
-The path of the workflow log can be set as follows:
+The path of the workflow log can be changed with:
 
 ::
 
-	occ config:app:set workflowengine logfile --value=/var/log/nextcloud/flow.log
+    occ config:app:set workflowengine logfile --value=/var/log/nextcloud/flow.log
+
+To disable workflow logging entirely, redirect the output to ``/dev/null``:
 
-Set the value to `/dev/null` to avoid storing the log.
+::
 
+    occ config:app:set workflowengine logfile --value=/dev/null
 
 Temporary overrides
 -------------------
 
-You can run override the config.php log level of ``occ`` commands with as :ref:`documented here<occ_debugging>`.
+You can override the config.php log level for ``occ`` commands as :ref:`documented here<occ_debugging>`.
+
+.. _PHP date function: http://www.php.net/manual/en/function.date.php