Skip to content

docs(admin): improve logging configuration accuracy, completeness, and clarity #14221

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
joshtrichards wants to merge 8 commits into
base: master
Choose a base branch
from
Open

docs(admin): improve logging configuration accuracy, completeness, and clarity #14221

Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
2aeb6ea
docs(admin): Add missing config parameters for file-based logging
joshtrichards Apr 1, 2026
b5e1e83
docs(admin): add "Conditional logging" (log.condition) coverage
joshtrichards Apr 1, 2026
a446acc
docs(admin): add missing log fields in the logging chapter
joshtrichards Apr 2, 2026
66ced55
docs(admin): update "Admin audit log" section accuracy and clarity
joshtrichards Apr 2, 2026
fb9fab4
chore(admin): drop outdated errorlog prefix note
joshtrichards Apr 2, 2026
8abbc77
docs(admin): expand/add context to the "Workflow log" section
joshtrichards Apr 2, 2026
0223a89
docs(admin): fix typo in Logging - "Temporary overrides"
joshtrichards Apr 2, 2026
12cd6ea
chore(admin): fixup updated logging chapter
joshtrichards Apr 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
313 changes: 278 additions & 35 deletions admin_manual/configuration_server/logging_configuration.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ All log information will be sent to PHP ``error_log()``.

"log_type" => "errorlog",

.. warning:: Until version Nextcloud 25 log entries were prefixed with ``[owncloud]``. From 26 onwards messages start with ``[nextcloud]``.
Log entries will be prefixed with ``[nextcloud]``.

file
~~~~
Expand All @@ -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
~~~~~~

Expand All @@ -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
--------------------

Expand Down Expand Up @@ -122,87 +293,159 @@ 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).

.. note::
Detailed documentation on auditable events for enterprises can be found in the Nextcloud GmbH
`customer portal <https://portal.nextcloud.com/article/using-the-audit-log-44.html>`_.
Copy link
Copy Markdown
Member

@rakekniven rakekniven Apr 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Remove walled link. This is not useful for doc readers.


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
Loading