mattermost · amyblais · May 15, 2026 · Apr 16, 2026 · Apr 16, 2026 · Apr 17, 2026
diff --git a/source/administration-guide/configure/environment-configuration-settings.rst b/source/administration-guide/configure/environment-configuration-settings.rst
@@ -833,13 +833,31 @@ Maximum idle connections
 Query timeout
 ~~~~~~~~~~~~~
 
-+--------------------------------------------------------+-------------------------------------------------------------------------+
-| The amount of time to wait, in seconds, for a response | - System Config path: **Environment > Database**                        |
++--------------------------------------------------------+----------------------------------------------------------------------------------+
+| The amount of time to wait, in seconds, for a response | - System Config path: **Environment > Database**                                 |
 | from the database after opening a connection and       | - ``config.json`` setting: ``SqlSettings`` > ``QueryTimeout`` > ``30``  |
-| sending the query.                                     | - Environment variable: ``MM_SQLSETTINGS_QUERYTIMEOUT``                 |
-|                                                        |                                                                         |
-| Numerical input in seconds. Default is **30** seconds. |                                                                         |
-+--------------------------------------------------------+-------------------------------------------------------------------------+
+| sending the query.                                     | - Environment variable: ``MM_SQLSETTINGS_QUERYTIMEOUT``                          |
+|                                                        |                                                                                  |
+| Numerical input in seconds. Default is **30** seconds. |                                                                                  |
++--------------------------------------------------------+----------------------------------------------------------------------------------+
+
+.. config:setting:: analytics-query-timeout
+  :displayname: Analytics Query timeout (Database)
+  :systemconsole: Environment > Database
+  :configjson: .SqlSettings.AnalyticsQueryTimeout
+  :environment: MM_SQLSETTINGS_ANALYTICSQUERYTIMEOUT
+  :description: The number of seconds to wait for a response from the database after opening a connection and sending certain analytics queries. This setting only applies to long queries which are run in the background to populate some information in the Team and Site Statistics pages. Default is **300** seconds.
+
+Analytics query timeout
+~~~~~~~~~~~~~~~~~~~~~~~
+
++--------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+
+| The number of seconds to wait for a response from the database after opening a connection  | - ``config.json`` setting: ``SqlSettings`` > ``AnalyticsQueryTimeout`` > ``300`` |
+| and sending certain analytics queries. This setting only applies to long queries which are | - System Config path: **Environment > Database**                                 |
+| run in the background to populate some information in the Team and Site Statistics pages.  | - Environment variable: ``MM_SQLSETTINGS_ANALYTICSQUERYTIMEOUT``                 |
+|                                                                                            |                                                                                  |
+| Numerical input in seconds. Default is **300** seconds.                                    |                                                                                  |
++--------------------------------------------------------------------------------------------+----------------------------------------------------------------------------------+
 
 .. config:setting:: maximum-connection-lifetime
   :displayname: Maximum connection lifetime (Database)

diff --git a/source/administration-guide/configure/system-attributes.rst b/source/administration-guide/configure/system-attributes.rst
@@ -10,6 +10,6 @@ Review and manage the following system attributes configuration options in the S
 
 You can define, manage, and enforce specific attributes, including:
 
-- **Custom attributes for user profiles**: Display details such as job titles, departments, or other metadata, on user profiles that align with your organizational structures and workflows. Learn more about :doc:`managing custom user profile attributes </administration-guide/manage/admin/user-attributes>`. API responses for custom profile attributes return default visibility and sort order when those values are missing.
+- **User attributes**: Display details such as job titles, departments, or other metadata, on user profiles that align with your organizational structures and workflows. Learn more about :doc:`managing user attributes </administration-guide/manage/admin/user-attributes>`. API responses for user attributes return default visibility and sort order when those values are missing.
 - **Granular access controls based on user attributes**: Ensure users have access to only the resources and functionality relevant to their roles, bolstering security and compliance across the organization. Learn more about :doc:`managing access based on user attributes </administration-guide/manage/admin/attribute-based-access-control>`.
 - **Control user-managed attributes in attribute-based access control (ABAC)**: From Mattermost v10.11 (Enterprise Edition Advanced), user-managed attributes are excluded from ABAC rules by default to prevent unauthorized access. System admins can enable them with a configuration setting. Learn more about enabling user-managed attributes in ABAC rules in the :ref:`User Attributes documentation <administration-guide/manage/admin/user-attributes:before you begin>`.
diff --git a/source/administration-guide/manage/admin/user-attributes.rst b/source/administration-guide/manage/admin/user-attributes.rst
@@ -11,7 +11,7 @@ System attributes enable you to customize user profile attributes to match your
 From Mattermost v11, you have enhanced control over these user attributes through admin-managed vs user-editable settings. By default, attributes are admin-managed for security, but you can explicitly allow user editing for specific attributes that don't impact access control or sensitive organizational data. These user attributes supplement existing user details visible from the user's profile picture.
 
 .. image:: ../../../images/cpa-properties.png
-  :alt: Mobile examples of a user profile with custom user attributes added as system attributes.
+  :alt: Mobile examples of a user profile with user attributes added as system attributes.
 
 Before you begin
 -----------------
@@ -126,11 +126,11 @@ Manage attributes
 - **Delete**: Delete attributes you no longer need or want by selecting **More** |more-icon| and selecting **Delete property**.
 
 .. note::
-  When updating custom profile attributes via API or automation, the ``attrs`` object replaces existing attribute settings rather than merging. If you send only visibility, the sort order resets to ``0`` unless you include ``sort_order`` in the same request. If a patch fails, the API may return the error string "Unable to patch Custom Profile Attribute field".
+  When updating user attributes via API or automation, the ``attrs`` object replaces existing attribute settings rather than merging. If you send only visibility, the sort order resets to ``0`` unless you include ``sort_order`` in the same request. If a patch fails, the API may return the error string "Unable to patch User Attribute field".
 
 - **User Edit Permissions**: From Mattermost v11, all user attributes are admin-managed by default for enhanced security. To allow user editing for specific attributes, administrators can enable this through the **More** |more-icon| menu and selecting **Allow user editing**. This should only be enabled for attributes that do not impact security access controls or organizational policies. Attributes used in ABAC policies should remain admin-managed unless there's a specific business need and the security implications are fully understood.
 
-- **Edit User Attribute Values**: From Mattermost v11.1, you can view and update custom profile attribute values for individual users through the System Console. See the :ref:`Manage user attributes <administration-guide/configure/user-management-configuration-settings:manage user attributes>` documentation for details.
+- **Edit User Attribute Values**: From Mattermost v11.1, you can view and update user attribute values for individual users through the System Console. See the :ref:`Manage user attributes <administration-guide/configure/user-management-configuration-settings:manage user attributes>` documentation for details.
 
 In cases where multiple system admins manage system attributes, refresh your web browser instance to see real-time updates to system attributes made by other admins.
 

diff --git a/source/administration-guide/manage/mmctl-command-line-tool.rst b/source/administration-guide/manage/mmctl-command-line-tool.rst
@@ -30,7 +30,7 @@ mmctl commands
 - `mmctl bot`_ - Bot Management
 - `mmctl channel`_ - Channel Management
 - `mmctl command`_ - Command Management
-- `mmctl cpa`_ - Custom Profile Attribute Management
+- `mmctl cpa`_ - User Attribute Management
 - `mmctl completion`_ - Generate autocompletion scripts for bash, fish, powershell, and zsh
 - `mmctl compliance-export`_ - Compliance Export Management
 - `mmctl config`_ - Configuration Management
@@ -2013,7 +2013,7 @@ mmctl cpa
 Manage User Attributes for extended user profile information.
 
    Child Commands
-      - `mmctl cpa field`_ - Manage CPA fields
+      - `mmctl cpa field`_ - Manage User Attribute fields
 
 **Options**
 
@@ -2026,13 +2026,13 @@ mmctl cpa field
 
 **Description**
 
-Manage Custom Profile Attribute fields.
+Manage User Attribute fields.
 
    Child Commands
-      - `mmctl cpa field create`_ - Create a new CPA field
-      - `mmctl cpa field delete`_ - Delete a CPA field
-      - `mmctl cpa field edit`_ - Edit a CPA field
-      - `mmctl cpa field list`_ - List CPA fields
+      - `mmctl cpa field create`_ - Create a new User Attribute field
+      - `mmctl cpa field delete`_ - Delete a User Attribute field
+      - `mmctl cpa field edit`_ - Edit a User Attribute field
+      - `mmctl cpa field list`_ - List User Attribute fields
 
 **Options**
 
@@ -2045,7 +2045,7 @@ mmctl cpa field create
 
 **Description**
 
-Create a new Custom Profile Attribute field.
+Create a new User Attribute field.
 
 **Format**
 
@@ -2088,7 +2088,7 @@ mmctl cpa field delete
 
 **Description**
 
-Delete an existing Custom Profile Attribute field.
+Delete an existing User Attribute field.
 
 **Format**
 
@@ -2129,7 +2129,7 @@ mmctl cpa field edit
 
 **Description**
 
-Edit an existing Custom Profile Attribute field.
+Edit an existing User Attribute field.
 
 **Format**
 
@@ -2174,7 +2174,7 @@ mmctl cpa field list
 
 **Description**
 
-List all Custom Profile Attribute fields.
+List all User Attribute fields.
 
 **Format**
 

diff --git a/...dministration-guide/scale/common-configure-mattermost-for-enterprise-search.rst b/...dministration-guide/scale/common-configure-mattermost-for-enterprise-search.rst
@@ -40,7 +40,7 @@ Set **Enable Elasticsearch for search queries** to ``true``, and setting **Enabl
 
 .. warning::
 
-   For high post volume deployments, we also strongly recommend *disabling* Database Search once Elasticsearch or AWS OpenSearch is fully configured and running. The Mattermost Server will fall back on Database search if ElasticSearch or OpenSearch are unavailable which can lead to performance degradation on high post volume deployments.
+   For high post volume deployments, we also strongly recommend *disabling* Database Search once Elasticsearch or AWS OpenSearch is fully configured and running. The Mattermost Server will fall back on Database search if Elasticsearch or OpenSearch are unavailable, which can lead to performance degradation on high post volume deployments. From Mattermost v11.7, the server proactively detects outages through periodic health checks and falls back to database search on the first health check failure, rather than waiting for requests to time out. See the :ref:`outage handling FAQ <administration-guide/scale/enterprise-search:how does mattermost handle elasticsearch or opensearch outages?>` for details.
 
 Once the configuration is saved, new posts made to the database are automatically indexed on the Elasticsearch or AWS OpenSearch server.
 

diff --git a/source/administration-guide/scale/enterprise-search.rst b/source/administration-guide/scale/enterprise-search.rst
@@ -129,6 +129,49 @@ From Mattermost v11, :doc:`Support Packet generation </administration-guide/mana
 
 The enterprise search connection test results appear in the Support Packet and can help identify configuration issues such as network connectivity problems, authentication failures, or server availability issues. If connection errors are present, they will be clearly documented with specific error messages to aid in troubleshooting.
 
+How does Mattermost handle Elasticsearch or OpenSearch outages?
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+From Mattermost v11.7, the server includes an automatic health monitor for Elasticsearch and OpenSearch connections. The health monitor runs periodic health checks and automatically manages the connection lifecycle:
+
+- **Health checks**: The server checks the health of the search engine cluster every 60 seconds. After 3 consecutive health check failures, the engine is stopped and search falls back to the database.
+- **Fast-fail on first failure**: On the very first health check failure, the engine is immediately marked as unhealthy and search requests are routed to the database. This happens before the consecutive failure threshold is reached, so users experience minimal disruption.
+- **Automatic retry**: When the search engine is unavailable, the server retries connecting with exponential backoff, starting at 15 seconds and doubling up to a maximum of 5 minutes between attempts.
+- **Automatic recovery**: When the search engine becomes available again, the server automatically reconnects and resumes using it for search queries. No manual intervention or server restart is required.
+- **Configuration changes**: Changes to Elasticsearch or OpenSearch configuration settings, or license changes, immediately trigger the health monitor to re-evaluate the connection state.
+- **Monitoring**: A ``mattermost_search_engine_status`` Prometheus metric reports the health of the search engine (``1`` = healthy or not configured, ``0`` = configured but unavailable). Use this metric to :doc:`set up alerts </administration-guide/scale/performance-alerting>` for search engine outages. See :doc:`performance monitoring metrics </administration-guide/scale/performance-monitoring-metrics>` for details.
+
+During an outage, you may see the following log messages:
+
+.. list-table::
+   :widths: 15 45 40
+   :header-rows: 1
+
+   * - Level
+     - Log message
+     - Meaning
+   * - Error
+     - ``Search engine health check failed repeatedly; stopping engine``
+     - The failure threshold was reached and the engine has been stopped. Search falls back to the database.
+   * - Warn
+     - ``Search engine health check failed``
+     - An individual health check failed. Includes a ``consecutive_failures`` count.
+   * - Warn
+     - ``Search engine health check failed: it is now marked as unhealthy``
+     - A previously healthy engine failed a health check and has been marked unhealthy. Search requests will fall back to the database immediately.
+   * - Warn
+     - ``Search engine watcher: Start() failed, will retry``
+     - A reconnection attempt failed. Includes a ``next_backoff`` field indicating the time until the next retry.
+   * - Info
+     - ``Search engine health check succeeded: it is now marked as healthy``
+     - The engine passed a health check after being unhealthy and is now handling search requests again.
+   * - Info
+     - ``Search engine watcher: engine started successfully``
+     - The engine has recovered and is active again.
+   * - Info
+     - ``Search engine watcher: engine disabled, parking``
+     - The health monitor is idle because the search engine is disabled in configuration.
+
 My search indexes won't complete, what should I do?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 

diff --git a/source/administration-guide/scale/performance-monitoring-metrics.rst b/source/administration-guide/scale/performance-monitoring-metrics.rst
@@ -118,6 +118,7 @@ Search metrics
 - ``mattermost_search_post_index_total``: The total number of posts indexes carried out.
 - ``mattermost_search_posts_searches_total``: The total number of post searches carried out.
 - ``mattermost_search_user_index_total``: The total number of user indexes carried out.
+- ``mattermost_search_engine_status``: Status of the configured search engine: ``1`` = healthy or not configured, ``0`` = configured but unavailable. Use this metric to set up alerts for search engine outages.
 
 WebSocket metrics
 ~~~~~~~~~~~~~~~~~