diff --git a/source/administration-guide/compliance-with-mattermost.rst b/source/administration-guide/compliance-with-mattermost.rst index 203091199cd..f311fdeb4f3 100644 --- a/source/administration-guide/compliance-with-mattermost.rst +++ b/source/administration-guide/compliance-with-mattermost.rst @@ -15,6 +15,7 @@ Mattermost is purpose-built to help enterprises keep sensitive data safe and com Export channel data Legal Hold JSON audit log schema + Post delivery audit logging * :doc:`Compliance exports ` - Export compliance reports to third-party systems to archive history. * :doc:`Compliance monitoring ` - Enable oversight and prevent unauthorized queries with compliance exports. @@ -22,4 +23,5 @@ Mattermost is purpose-built to help enterprises keep sensitive data safe and com * :doc:`Data retention ` - Control how long data is stored in Mattermost with global and custom retention policies to meet data retention compliance requirements. * :doc:`Export channel data ` - Migrate data between systems and back data up for operational continuity. * :doc:`Legal Hold ` - Preserve relevant Mattermost information when litigation is anticipated. -* :doc:`JSON audit log schema ` - Learn how to configure Mattermost audit logging using a JSON object. \ No newline at end of file +* :doc:`JSON audit log schema ` - Learn the JSON structure of Mattermost audit log entries. +* :doc:`Post delivery audit logging ` - Record an audit log entry each time a message is delivered to a user, to establish which users a given message reached. \ No newline at end of file diff --git a/source/administration-guide/comply/embedded-json-audit-log-schema.rst b/source/administration-guide/comply/embedded-json-audit-log-schema.rst index 75a0d4d5675..e4e11ffbb35 100644 --- a/source/administration-guide/comply/embedded-json-audit-log-schema.rst +++ b/source/administration-guide/comply/embedded-json-audit-log-schema.rst @@ -356,6 +356,19 @@ Posts & Content Events .. note:: From Mattermost v11.5.0, audit log entries for posts and content access events include a ``non_channel_member_access`` field in the ``meta`` object. When a user accesses posts or content in a channel they are not a member of, this field is set to ``true``. Admins can use this indicator to identify and review unauthorized or unexpected content access in their audit logs. +Post Delivery Events +~~~~~~~~~~~~~~~~~~~~ + +Mattermost v12.0 introduces the ``postDelivered`` audit log event, which records each delivery of a message's content to a user or an integration. It's emitted only when :doc:`post delivery audit logging ` is enabled, which is disabled by default. Unlike the other audit log events on this page, ``postDelivered`` is emitted at the dedicated ``audit-delivery`` log level and so requires its own audit log target. See that page for the record format, the payload fields, and the full set of delivery mechanisms. + ++----------------------------------+-------------------------------------------------------------------+ +| **Event Name** | **Description** | ++==================================+===================================================================+ +| ``postDelivered`` | Delivering post content to a user or integration | ++----------------------------------+-------------------------------------------------------------------+ +| ``updateDeliveryTrackingConfig`` | Updating the post delivery audit logging configuration | ++----------------------------------+-------------------------------------------------------------------+ + Authentication and Security Events ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/source/administration-guide/comply/post-delivery-audit-logging.rst b/source/administration-guide/comply/post-delivery-audit-logging.rst new file mode 100644 index 00000000000..66720c1fded --- /dev/null +++ b/source/administration-guide/comply/post-delivery-audit-logging.rst @@ -0,0 +1,214 @@ +Post delivery audit logging +============================ + +.. include:: ../../_static/badges/entry-adv.rst + :start-after: :nosearch: + +From Mattermost v12.0, Mattermost can record an audit log entry each time a message's content is delivered to a user or to an integration. These records let you establish which users a given message was delivered to, and by what means. + +.. note:: + + Post delivery audit logging is currently in :ref:`Beta `. + +Delivery records are ordinary audit log records, written through the existing audit logging pipeline to whichever audit log targets you've configured. + +Before you begin +---------------- + +Post delivery audit logging requires all of the following: + +- A Mattermost Enterprise Advanced license. +- The `feature flag `_ ``MM_FEATUREFLAGS_POSTDELIVERYTRACKING``, which is disabled by default. **Restart the server after enabling the feature flag**. +- Advanced Logging > Advanced Logging to be enabled +- An audit log target that consumes the ``audit-delivery`` log level in the advanced audit log config. + +.. important:: + + Enabling post delivery audit logging on its own produces no output. Delivery records are discarded until an audit log target consumes the ``audit-delivery`` log level. Configure the target before you enable the feature. The log volume increases substantially once these audit logs are enabled. + +Configure an audit log target +----------------------------- + +Delivery records are written at the ``audit-delivery`` log level, ID ``104``. Unlike the other :ref:`audit log levels `, ``audit-delivery`` isn't written by the built-in audit log file target, so enabling ``ExperimentalAuditSettings.FileEnabled`` doesn't capture delivery records. Add a target that consumes level ``104`` to ``ExperimentalAuditSettings.AdvancedLoggingJSON`` instead. See :ref:`advanced logging ` for the available target types and options. + +We recommend a dedicated target, so that the volume of delivery records doesn't overwhelm your other audit records. The example below writes delivery records to their own file, rotated at 100 MB, with up to 10,000 records buffered in memory while writing: + +.. code-block:: JSON + + { + "post-delivery-audit": { + "type": "file", + "format": "json", + "levels": [ + { "id": 104, "name": "audit-delivery" } + ], + "options": { + "filename": "./logs/post-delivery-audit.log", + "max_size": 100, + "max_age": 0, + "max_backups": 0, + "compress": true + }, + "maxqueuesize": 10000 + } + } + +If post delivery audit logging is enabled and no audit log target consumes the ``audit-delivery`` level, the configuration remains valid, delivery records are discarded, and Mattermost logs the following warning at startup and whenever the configuration changes: + +.. code-block:: text + + DeliveryTrackingSettings.Enable is enabled but no configured audit log target consumes the audit-delivery level; post delivery audit records will be discarded. Add a target for the level via ExperimentalAuditSettings.AdvancedLoggingJSON. + +Enable post delivery audit logging +---------------------------------- + +In the System Console, enable post delivery audit logging and choose the channels that deliveries are recorded in by going to **Site Configuration > Data Spillage Handling > Post Delivery Audit Logging**. See :ref:`administration-guide/manage/admin/content-flagging:post delivery audit logging` for the steps, and :ref:`administration-guide/configure/site-configuration-settings:content flagging` for the corresponding ``config.json`` settings and environment variables. + +Record format +------------- + +Each delivery is recorded as a ``postDelivered`` audit log record. The ``status`` of the record is always ``success``. + +**The recipient of the message is the actor of the record**, in ``actor.user_id``. There's no separate recipient field. This lets you group records by actor to answer "what was delivered to this user". Deliveries to a plugin or to an outgoing webhook have no human recipient, so ``actor.user_id`` is empty and ``meta.plugin_id`` or ``meta.webhook_id`` identifies the integration instead. + +The ``meta`` object identifies what was delivered and how. Unlike audit records emitted from a REST API request, delivery records carry no ``api_path`` or ``cluster_id`` in ``meta``. + +A message delivered to a user through the Mattermost REST API: + +.. code-block:: json + + { + "timestamp": "2026-08-12 14:03:11.482 Z", + "event_name": "postDelivered", + "status": "success", + "actor": { + "user_id": "hx4k9m2qzbfytr7wn6cbd3jvse", + "session_id": "", + "client": "", + "ip_address": "" + }, + "meta": { + "post_id": "xpw97hf6kfncirzhqisb5sym7e", + "channel_id": "pfis7ycuy78o7m3zebajmxqeuo", + "mechanism": "product" + }, + "error": {} + } + +The same message delivered to a plugin, with no human recipient: + +.. code-block:: json + + { + "timestamp": "2026-08-12 14:03:11.509 Z", + "event_name": "postDelivered", + "status": "success", + "actor": { + "user_id": "", + "session_id": "", + "client": "", + "ip_address": "" + }, + "meta": { + "post_id": "xpw97hf6kfncirzhqisb5sym7e", + "channel_id": "pfis7ycuy78o7m3zebajmxqeuo", + "mechanism": "plugin", + "plugin_id": "com.mattermost.example-plugin" + }, + "error": {} + } + +See the :doc:`audit log JSON schema ` for the fields common to every Mattermost audit log record. + +Payload fields +-------------- + +The ``meta`` object of a ``postDelivered`` record contains the following fields. The recipient isn't in ``meta`` — the recipient is the actor of the record, in ``actor.user_id``. + ++--------------------+---------------+-----------------------------------------------------------------------+ +| **Field name** | **Data type** | **Description** | ++====================+===============+=======================================================================+ +| post_id | string | Always present. The unique identifier of the message whose content | +| | | was delivered. | ++--------------------+---------------+-----------------------------------------------------------------------+ +| channel_id | string | Always present. The unique identifier of the channel that the message | +| | | belongs to. | ++--------------------+---------------+-----------------------------------------------------------------------+ +| mechanism | string | Always present. How the message content reached the recipient. See | +| | | `delivery mechanisms <#delivery-mechanisms>`__ for the possible | +| | | values. | ++--------------------+---------------+-----------------------------------------------------------------------+ +| plugin_id | string | Present for ``plugin`` deliveries only. The plugin that the message | +| | | content was passed to. | ++--------------------+---------------+-----------------------------------------------------------------------+ +| webhook_id | string | Present for ``outgoing_webhook`` deliveries only. The outgoing | +| | | webhook that the message content was sent to. | ++--------------------+---------------+-----------------------------------------------------------------------+ +| via_post_id | string | Present for ``permalink_preview`` deliveries only. The message that | +| | | embedded the permalink preview. | ++--------------------+---------------+-----------------------------------------------------------------------+ +| via_channel_id | string | Present for ``permalink_preview`` deliveries only. The channel | +| | | containing the message that embedded the permalink preview. | ++--------------------+---------------+-----------------------------------------------------------------------+ + +Delivery mechanisms +------------------- + +The ``mechanism`` field records how the message content reached the recipient. It's always one of the following seven values: + ++-----------------------+--------------------------------------------------------------------------------+ +| **Value** | **Delivery** | ++=======================+================================================================================+ +| ``product`` | Any read of message content through the Mattermost REST API. This covers | +| | channel loads, thread and reply views, search results, direct fetches of a | +| | message by ID, pinned messages, saved messages, and message edit history. | ++-----------------------+--------------------------------------------------------------------------------+ +| ``post_broadcast`` | A new or edited message pushed over WebSocket to connected channel members. | ++-----------------------+--------------------------------------------------------------------------------+ +| ``permalink_preview`` | A message rendered as a permalink preview inside another message. | ++-----------------------+--------------------------------------------------------------------------------+ +| ``email`` | Message content included in a notification email. | ++-----------------------+--------------------------------------------------------------------------------+ +| ``push`` | Message content included in a push notification payload, and the | +| | acknowledgement fetch that retrieves content for an ID-only push notification. | ++-----------------------+--------------------------------------------------------------------------------+ +| ``outgoing_webhook`` | Message content sent to an outgoing webhook. | ++-----------------------+--------------------------------------------------------------------------------+ +| ``plugin`` | A message passed to a plugin's ``MessageWillBePosted`` or | +| | ``MessageWillBeUpdated`` hook, or read through the plugin API. | ++-----------------------+--------------------------------------------------------------------------------+ + +.. note:: + + Channel loads, thread views, search results, and direct message fetches all share the ``product`` value. They aren't reported as separate mechanisms. + +What isn't recorded +------------------- + +The following are never recorded: + +- **The message author**: A user never receives a delivery record for their own message. +- **System messages and ephemeral messages**. +- **Burn-on-read messages**. +- **Direct and group messages**: These channels are never eligible, including when deliveries are recorded in all channels. +- **Generic push notifications**: A push notification that doesn't include message content records nothing. When push notifications are configured to send only IDs, the delivery is recorded when the device fetches the content. +- **Plugins reading from the database**: A plugin that reads messages directly from the database, rather than through the plugin API or a message hook, can't be observed and isn't recorded. + +Messages posted by bots and by outgoing webhooks are recorded like any other message. + +Interpret delivery records +-------------------------- + +Mattermost records one entry for each message delivered to each recipient, with no batching. A channel load that returns 100 messages produces 100 records, and a new message broadcast to 40 connected channel members produces 40 records. + +Delivery records are an append-only event stream, not a deduplicated list of who has seen a message. The same combination of user, message, and mechanism recurs, because every time a user revisits a channel the same page of messages is delivered again. Each record is a genuine delivery with its own timestamp. + +Deduplicate on ``actor.user_id``, ``meta.post_id``, and ``meta.mechanism`` to get one entry per recipient, message, and delivery mechanism, taking the earliest timestamp in each group as the first delivery by that mechanism. A recipient who received the same message by more than one mechanism — for example ``push`` and then ``product`` — has one entry per mechanism. + +To reduce that to a distinct list of the users a message reached, drop ``meta.mechanism`` from the key and deduplicate on ``actor.user_id`` and ``meta.post_id`` alone. + +Keep the following in mind when working with delivery records: + +- **Delivery isn't proof of reading**: A record means Mattermost transmitted the message content to an endpoint the recipient could read it from. It doesn't mean anyone read it. A user with email notifications configured to include message content is recorded as a delivery even if they never opened Mattermost. +- **Records aren't guaranteed to be complete**: Audit logging is asynchronous, so records still queued in memory are lost if the server stops uncleanly. A controlled shutdown flushes the queue. This is existing audit logging behaviour that applies to all audit log levels. +- **Permalink previews follow the previewed message**: Whether a permalink preview delivery is recorded depends on the channel of the message being previewed, not the channel of the message containing the preview. A preview of a message in a recorded channel is recorded even when the preview is rendered in a channel that isn't. Without this, a recorded message could be read by permalinking it into any other channel. Mattermost renders one level of permalink preview, so one level is recorded. diff --git a/source/administration-guide/configure/environment-configuration-settings.rst b/source/administration-guide/configure/environment-configuration-settings.rst index f3714c6ec9d..82172d7edaf 100644 --- a/source/administration-guide/configure/environment-configuration-settings.rst +++ b/source/administration-guide/configure/environment-configuration-settings.rst @@ -3932,6 +3932,7 @@ Output audit logs to multiple targets - See the :doc:`Mattermost logging ` documentation for details on advanced logging configuration. These targets have been chosen as they support the vast majority of log aggregators, and other log analysis tools, without needing additional software installed. - Audit logs are recorded asynchronously to reduce latency to the caller. - Advanced audit logging supports hot-reloading of logger configuration. + - From Mattermost v12.0, the ``audit-delivery`` log level isn't written by the built-in audit log file target, so :ref:`post delivery audit records ` are discarded unless you add a target here whose ``levels`` list includes ``{"id": 104, "name": "audit-delivery"}``. ---- diff --git a/source/administration-guide/configure/site-configuration-settings.rst b/source/administration-guide/configure/site-configuration-settings.rst index 839b5074260..b79bc3be22f 100644 --- a/source/administration-guide/configure/site-configuration-settings.rst +++ b/source/administration-guide/configure/site-configuration-settings.rst @@ -2259,6 +2259,86 @@ Team administrators as reviewers | as reviewers. | | +-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+ +From Mattermost v12.0, the following settings control post delivery audit logging, which records an audit log entry for each delivery of a message in an eligible channel. Delivery records require an audit log target that consumes the ``audit-delivery`` log level. See :doc:`Post delivery audit logging ` for details. + +.. important:: + + Post delivery audit logging is currently in :ref:`Beta `. It requires the `feature flag `_ ``MM_FEATUREFLAGS_POSTDELIVERYTRACKING``, which is disabled by default, and a server restart after you enable it. It also requires an audit log target that consumes the ``audit-delivery`` log level. + +.. config:setting:: delivery-tracking-enable + :displayname: Enable post delivery audit logging (Data Spillage Handling) + :systemconsole: Site Configuration > Data Spillage Handling + :configjson: .DeliveryTrackingSettings.Enable + :environment: MM_DELIVERYTRACKINGSETTINGS_ENABLE + :description: Record an audit log entry for each delivery of a message in an eligible channel. Default is **false**. + + - **true**: An audit log entry is recorded for each delivery of a message in an eligible channel. + - **false**: **(Default)** Message deliveries aren't recorded. + +Enable post delivery audit logging +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ++-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+ +| - **true**: An audit log entry is recorded each time | - System Config path: **Site Configuration > Data Spillage Handling** | +| a message is delivered to a user. | - ``config.json`` setting: ``DeliveryTrackingSettings`` > ``Enable`` > ``false`` | +| - **false**: **(Default)** Message deliveries aren't | - Environment variable: ``MM_DELIVERYTRACKINGSETTINGS_ENABLE`` | +| recorded. | | ++-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+ + +Delivery records are written to the audit log only, and aren't surfaced anywhere in the Mattermost interface. + +.. warning:: + + Delivery records are discarded unless an audit log target consumes the ``audit-delivery`` log level. Setting this to **true** without configuring such a target records nothing, and Mattermost doesn't block the configuration. See :doc:`Post delivery audit logging `. + +.. config:setting:: delivery-tracking-all-channels + :displayname: Record deliveries in (Data Spillage Handling) + :systemconsole: Site Configuration > Data Spillage Handling + :configjson: .DeliveryTrackingSettings.EnableForAllChannels + :environment: MM_DELIVERYTRACKINGSETTINGS_ENABLEFORALLCHANNELS + :description: Record message deliveries in all eligible channels, or only in selected channels. Default is **true**. + + - **true**: **(Default)** Deliveries are recorded in all eligible channels. + - **false**: Deliveries are recorded only in the selected channels. + +Record deliveries in +~~~~~~~~~~~~~~~~~~~~ + ++-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+ +| - **true**: **(Default)** Deliveries are recorded in | - System Config path: **Site Configuration > Data Spillage Handling** | +| all eligible channels. | - ``config.json`` setting: ``DeliveryTrackingSettings`` > ``EnableForAllChannels`` > ``true`` | +| - **false**: Deliveries are recorded only in the | - Environment variable: ``MM_DELIVERYTRACKINGSETTINGS_ENABLEFORALLCHANNELS`` | +| selected channels. | | ++-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+ + +.. note:: + + Recording deliveries in all eligible channels is the most complete option, and also the most expensive. Direct and group messages are never eligible, regardless of this setting. + +.. config:setting:: delivery-tracking-channels + :displayname: Channels to record deliveries in (Data Spillage Handling) + :systemconsole: Site Configuration > Data Spillage Handling + :configjson: N/A + :environment: N/A + :description: The channels in which message deliveries are recorded when deliveries aren't recorded in all channels. The list is stored in the database, so there's no ``config.json`` setting and no environment variable. Manage it in the System Console, or through the ``/api/v4/delivery_tracking/config`` API endpoints. + +Channels to record deliveries in +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + ++-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+ +| The channels in which message deliveries are | - System Config path: **Site Configuration > Data Spillage Handling** | +| recorded. Applies only when **Record deliveries in** | - ``config.json`` setting: N/A | +| is set to **Selected channels**, in which case at | - Environment variable: N/A | +| least one channel is required. | | +| | | +| Stored in the database, so there's no | | +| ``config.json`` setting and no environment variable. | | +| Manage the list in the System Console, or through the | | +| ``/api/v4/delivery_tracking/config`` API endpoints. | | +| | | +| Direct and group message channels can't be selected. | | ++-------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------+ + ---- File sharing and downloads diff --git a/source/administration-guide/manage/admin/content-flagging.rst b/source/administration-guide/manage/admin/content-flagging.rst index 58738cad245..7809cfee796 100644 --- a/source/administration-guide/manage/admin/content-flagging.rst +++ b/source/administration-guide/manage/admin/content-flagging.rst @@ -59,6 +59,14 @@ Configure - **Require reviewers to add comment**: Set to **True** to require reviewers to add a comment when resolving a quarantine. - **Hide message from channel while it is being reviewed**: Set to **True** to automatically hide quarantined messages from the channel until reviews are complete. If a root post is quarantined, the entire thread is hidden. +4. Under **Post Delivery Audit Logging**, record each user, plugin, and outgoing webhook that a message is delivered to: + + - **Enable post delivery audit logging**: Set to **True** to record an audit log entry for each delivery of a message in an eligible channel. These records are written to the audit log only, and aren't surfaced anywhere in the Mattermost interface. + - **Record deliveries in**: Select **All channels**, or select **Selected channels** to limit recording to specific channels. + - **Channels to record deliveries in**: With **Selected channels** set, select the channels in which deliveries are recorded. + + Direct and group message channels are never eligible, regardless of **Record deliveries in**. See :ref:`administration-guide/manage/admin/content-flagging:post delivery audit logging` for details. + .. tip:: We recommend enabling **Hide message from channel while it is being reviewed** and require comments from both reporters and reviewers to maintain transparency, accountability, and an auditable record of actions. @@ -188,6 +196,45 @@ When any step reports **Partial** or **Failed**, the report displays an *incompl The post deletion report is the single source of truth for post-removal auditing. It isn't stored elsewhere in the System Console, so the reviewer thread containing the report should be retained in line with your organization's audit retention policy. +Post delivery audit logging +--------------------------- + +From Mattermost v12.0, Mattermost can record an audit log entry for each delivery of a message in an eligible channel, so that you can establish which users, plugins, and outgoing webhooks a given message was delivered to. Direct and group message channels are never eligible. Delivery records add storage and processing cost, so enable them only where they're needed. + +.. note:: + + Post delivery audit logging is currently in :ref:`Beta `. + +Delivery records are written to the audit log only. They aren't surfaced anywhere in the Mattermost interface, and they aren't included in any Mattermost report. To use them, ingest them with the same pipeline you use for the rest of your Mattermost audit log. + +.. important:: + + Post delivery audit logging requires the `feature flag `_ ``MM_FEATUREFLAGS_POSTDELIVERYTRACKING``, which is disabled by default, and a server restart after you enable it. + +.. warning:: + + Delivery records are discarded unless an audit log target consumes the ``audit-delivery`` log level. Enabling the setting without configuring such a target records nothing, and Mattermost doesn't block the configuration. Configure the target first. + +To enable post delivery audit logging: + +1. Add an audit log target that consumes the ``audit-delivery`` log level. See :doc:`Post delivery audit logging `. +2. Go to **System Console > Site Configuration > Data Spillage Handling**, and find **Post Delivery Audit Logging**. +3. Set **Enable post delivery audit logging** to **True**. +4. Set **Record deliveries in**: + + - **All channels**: Deliveries are recorded in every eligible channel. This is the most complete option, and the most expensive. + - **Selected channels**: Deliveries are recorded only in the eligible channels you select. At least one channel is required. + +5. With **Selected channels** set, use **Channels to record deliveries in** to select the channels. Direct and group message channels can't be selected. Recording starts when you save and applies to eligible message content delivered from then on, including existing messages delivered through later channel loads, searches, and fetches. + +**Enable post delivery audit logging** and **Record deliveries in** can also be configured via the :ref:`config.json file or through environment variables `. + +The list of channels isn't stored in ``config.json``. Mattermost stores it in the database, so manage it either in the System Console or through the ``/api/v4/delivery_tracking/config`` API endpoints. A ``PUT`` request that omits ``ChannelIds`` leaves the stored list unchanged, and an empty array clears it. See the `Mattermost API reference `__. + +.. tip:: + + See :doc:`Post delivery audit logging ` for the format of a delivery record, every delivery mechanism that's recorded, what isn't recorded, and how to interpret the records. + Best practice recommendations ----------------------------- diff --git a/source/administration-guide/manage/logging.rst b/source/administration-guide/manage/logging.rst index 71e657805b6..ba45e280b92 100644 --- a/source/administration-guide/manage/logging.rst +++ b/source/administration-guide/manage/logging.rst @@ -38,6 +38,8 @@ System admins can customize the following logging options based on your business - Audit logging configurations reject standard log levels (``debug``, ``info``, ``warn``, ``error``, ``fatal``, ``panic``, etc.) - Configuration validation occurs at startup and when updating settings, preventing invalid log level combinations + From Mattermost v12.0, standard logging configurations also reject the ``audit-delivery`` log level. + Console logs ------------ @@ -212,7 +214,7 @@ Audit logging By default, Mattermost doesn't write audit logs locally to a file on the server, and the ability to enable audit logging in Mattermost is currently in :ref:`Beta `. -You can enable and customize advanced audit logging in Mattermost to record activities and events performed within Mattermost, such as user access to the Mattermost REST API or mmctl. Audit logs are recorded asynchronously to reduce latency to the caller, and are stored separately from general logging. During short spans of inability to write to targets, the audit records buffer in memory with a configurable maximum record cap. Based on typical audit record volumes, it could take many minutes to fill the buffer. After that, the records are dropped, and the record drop event is logged. +You can enable and customize advanced audit logging in Mattermost to record activities and events performed within Mattermost, such as user access to the Mattermost REST API or mmctl. Audit logs are recorded asynchronously to reduce latency to the caller, and are stored separately from general logging. During short spans of inability to write to targets, the audit records buffer in memory with a configurable maximum record cap. Based on typical audit record volumes, it could take many minutes to fill the buffer. After that, the records are dropped, and the record drop event is logged. From Mattermost v12.0, this shared audit queue holds up to 10,000 records, increased from 1,000. It's separate from the per-target ``maxqueuesize`` option, which caps the queue of an individual output target and is unchanged. .. note:: @@ -690,6 +692,15 @@ The following log levels support audit logs: +--------+-----------------------+------------------------------------------------------------------------+ | 103 | ``audit-cli`` | CLI operations | +--------+-----------------------+------------------------------------------------------------------------+ +| 104 | ``audit-delivery`` | Deliveries of message content to users, plugins, and outgoing | +| | | webhooks in eligible channels. Direct and group message channels are | +| | | never eligible. Available from Mattermost v12.0. This log level | +| | | generates considerably more records than any other audit log level. | ++--------+-----------------------+------------------------------------------------------------------------+ + +.. warning:: + + The ``audit-delivery`` log level isn't written by the built-in audit log file target, so enabling ``ExperimentalAuditSettings.FileEnabled`` doesn't capture delivery records — they're discarded. To capture them, add a target whose ``levels`` list includes ``{"id": 104, "name": "audit-delivery"}`` to ``ExperimentalAuditSettings.AdvancedLoggingJSON``. See :doc:`Post delivery audit logging `. The following log levels support application logs: