PS-11471 [DOCS] - Production readiness document 8.4

	new file:   docs/production-readiness.md
	modified:   mkdocs-base.yml

Author: patrickbirch

docs/production-readiness.md

@@ -0,0 +1,312 @@
+# Production readiness and baseline configuration
+
+Prepare each production host after you install Percona Server for MySQL.
+
+Use these values as a baseline. Test each value with a representative workload. Change one value at a time.
+
+!!! important
+
+    Test this configuration in a test environment before production use.
+
+    Memory, storage latency, concurrency, durability, and replication affect the correct values.
+
+## Day-1 checklist
+
+### Storage
+
+* Place data files, redo logs, binary logs, and temporary files on storage with predictable latency.
+
+* Confirm that the Linux file system supports direct input/output (I/O).
+
+* Monitor free space for each data directory and log directory.
+
+* Store backups outside the database host.
+
+* Test a restore from the backup.
+
+MySQL 8.4 uses `O_DIRECT` for `innodb_flush_method` when Linux supports the option. MySQL uses `fsync` as the fallback.
+
+Check the active flush method:
+
+```sql
+SHOW VARIABLES LIKE 'innodb_flush_method';
+```
+
+??? example "Expected output"
+
+    ```{.text .no-copy}
+    +---------------------+----------+
+    | Variable_name       | Value    |
+    +---------------------+----------+
+    | innodb_flush_method | O_DIRECT |
+    +---------------------+----------+
+    ```
+
+    MySQL returns `fsync` when the Linux file system lacks direct I/O support.
+
+### Memory
+
+* Set `innodb_buffer_pool_size` to 60–70% of physical random-access memory (RAM) on a dedicated database host.
+
+* Use a lower percentage when MySQL shares the host with other services.
+
+* Reserve memory for the operating system, Performance Schema, connections, temporary tables, sorts, replication, and backup tools.
+
+* Test the highest expected connection count.
+
+* Monitor swap use, resident memory, buffer pool hit rate, and temporary table use.
+
+Connection buffers use memory only when a connection needs each buffer. Actual use depends on workload concurrency.
+
+### Connections
+
+* Add all application connection pool limits.
+
+* Add connections for administration and metrics collection.
+
+* Add a small margin for failures.
+
+* Use the result for `max_connections`.
+
+* Set limits on application connection pools.
+
+* Queue or reject excess application work before MySQL reaches capacity.
+
+* Reserve access for database administrators.
+
+* Create an alert for high connection use.
+
+Use the default one-thread-per-connection model for most workloads. Consider the Percona thread pool after tests show a high-concurrency requirement. The thread pool usually offers little benefit below 20,000 connections.
+
+Check active, peak, and maximum connection values:
+
+```sql
+SHOW GLOBAL STATUS WHERE Variable_name IN ('Threads_connected', 'Max_used_connections');
+SHOW VARIABLES LIKE 'max_connections';
+```
+
+??? example "Expected output"
+
+    ```{.text .no-copy}
+    +----------------------+-------+
+    | Variable_name        | Value |
+    +----------------------+-------+
+    | Max_used_connections | 84    |
+    | Threads_connected    | 32    |
+    +----------------------+-------+
+
+    +-----------------+-------+
+    | Variable_name   | Value |
+    +-----------------+-------+
+    | max_connections | 200   |
+    +-----------------+-------+
+    ```
+
+    The connection values depend on the workload. `Max_used_connections` must remain below `max_connections`.
+
+### Logs and observability
+
+* Collect, retain, and monitor the error log.
+
+* Enable the slow query log with a cautious threshold.
+
+* Adjust the threshold and sample rate after you measure log volume.
+
+* Use `log_output=FILE` when Percona Monitoring and Management (PMM) Query Analytics reads the slow query log.
+
+* Define retention and rotation for error, slow, binary, and audit logs.
+
+* Create alerts for availability, disk space, replication lag, connection pressure, and resource saturation.
+
+Logs can use substantial I/O capacity and disk space.
+
+## Recommended production `my.cnf` baseline
+
+Configure a dedicated MySQL host as follows:
+
+* Run a Linux operating system.
+
+* Allocate 16 GiB of RAM.
+
+* Use a solid-state drive (SSD) or Non-Volatile Memory Express (NVMe) storage device.
+
+Replace each value marked `CHANGE` before deployment.
+
+Package installs often load extra configuration files from `/etc/mysql/conf.d/` or `/etc/my.cnf.d/`. Use the path for your operating system.
+
+```ini
+[mysqld]
+
+# Memory
+# CHANGE: Use 60-70% of RAM on a dedicated database host.
+# 11G is about 70% of the RAM on a 16 GiB host.
+innodb_buffer_pool_size = 11G
+
+# Connections
+# CHANGE: Add application pool limits, metrics collection, and an administrative margin.
+max_connections = 200
+
+# Storage and durability
+# MySQL 8.4 selects O_DIRECT on supported Linux systems.
+# Set this value only after you validate the file system and storage.
+# innodb_flush_method = O_DIRECT
+innodb_flush_log_at_trx_commit = 1
+sync_binlog = 1
+
+# Logs
+log_output = FILE
+slow_query_log = ON
+long_query_time = 1
+log_slow_verbosity = standard
+
+# Keep binary logs for point-in-time recovery and replication.
+# CHANGE: Choose a retention period from the backup and recovery policy.
+binlog_expire_logs_seconds = 604800
+```
+
+??? example "Expected result"
+
+    The configuration file contains one `[mysqld]` section with the selected production values.
+
+The durability values protect committed transactions during an operating system or host failure.
+
+Lower values for `innodb_flush_log_at_trx_commit` or `sync_binlog` can increase throughput. This change can also create a documented data loss period.
+
+Complete these steps before you restart the server:
+
+1. Save a copy of the active configuration.
+
+2. Replace the memory, connection, and retention values.
+
+3. Validate the configuration:
+
+    ```shell
+    mysqld --validate-config
+    ```
+
+    ??? example "Expected output"
+
+        A valid configuration produces no output. The command returns exit status zero.
+
+4. Restart MySQL during a maintenance period.
+
+5. Check the service state and error log.
+
+6. Confirm the active values:
+
+    ```sql
+    SHOW VARIABLES WHERE Variable_name IN (
+        'binlog_expire_logs_seconds',
+        'innodb_buffer_pool_size',
+        'innodb_flush_log_at_trx_commit',
+        'innodb_flush_method',
+        'log_output',
+        'log_slow_verbosity',
+        'long_query_time',
+        'max_connections',
+        'slow_query_log',
+        'sync_binlog'
+    );
+    ```
+
+    ??? example "Expected output"
+
+        ```{.text .no-copy}
+        +------------------------------------+-------------+
+        | Variable_name                      | Value       |
+        +------------------------------------+-------------+
+        | binlog_expire_logs_seconds         | 604800      |
+        | innodb_buffer_pool_size            | 11811160064 |
+        | innodb_flush_log_at_trx_commit     | 1           |
+        | innodb_flush_method                | O_DIRECT    |
+        | log_output                         | FILE        |
+        | log_slow_verbosity                 | standard    |
+        | long_query_time                    | 1.000000    |
+        | max_connections                    | 200         |
+        | slow_query_log                     | ON          |
+        | sync_binlog                        | 1           |
+        +------------------------------------+-------------+
+        ```
+
+        MySQL can return `fsync` for `innodb_flush_method`. The value depends on direct I/O support.
+
+### MySQL 8.4 defaults
+
+Review each MySQL 8.0 override before you use the override with MySQL 8.4.
+
+MySQL 8.4 has the following defaults:
+
+* `innodb_adaptive_hash_index=OFF`.
+
+* `innodb_change_buffering=none`.
+
+* `innodb_flush_method=O_DIRECT` on supported Linux systems. MySQL uses `fsync` as the fallback.
+
+* `innodb_io_capacity=10000`. This value targets SSD and NVMe storage. Hard disk drives may require a lower value.
+
+* `innodb_log_buffer_size=64M`.
+
+* `innodb_numa_interleave=ON`.
+
+* `temptable_max_ram` uses 3% of total memory. The minimum value is 1 GiB. The maximum value is 4 GiB.
+
+Read [Defaults and tuning guidance for MySQL 8.4](8.4-defaults-and-tuning.md) for more details.
+
+## Percona feature quick-activation matrix
+
+Each command requires the related package or component library. Run Structured Query Language (SQL) commands with the required administrative privileges.
+
+Some features also require tables or policy definitions. Follow the linked procedure before activation.
+
+| Feature | Activation | Production requirement |
+|---|---|---|
+| Thread pool | Add `thread_handling=pool-of-threads` under `[mysqld]`. Restart MySQL. | Use the feature only after high-concurrency tests show a benefit. Read [Thread pool](threadpool.md). |
+| Audit Log Filter | Run `SET GLOBAL audit_log_filter.disable = false;` after component installation and filter assignment. | Complete the [Audit Log Filter installation](install-audit-log-filter.md) and [Audit Log Filter quickstart](audit-log-filter-quickstart.md). Define production filters and retention. |
+| Data Masking | Create `mysql.masking_dictionaries`. Run `INSTALL COMPONENT 'file://component_masking_functions';`. | Use views and privileges to restrict access to unmasked data. Read [Install the data masking component](install-data-masking-component.md). |
+| Extended Slow Log | Add `slow_query_log=ON` and `log_slow_verbosity=standard` under `[mysqld]`. | Start with `long_query_time=1`. Measure log volume. Use `log_slow_rate_limit` when you need a sample. Read [Slow query log](slow-extended.md). |
+
+Verify each feature:
+
+```sql
+SHOW VARIABLES LIKE 'thread_handling';
+SHOW GLOBAL STATUS LIKE 'audit_log_filter_events_written';
+SELECT * FROM mysql.component
+WHERE component_urn = 'file://component_masking_functions';
+SHOW VARIABLES WHERE Variable_name IN (
+    'slow_query_log',
+    'log_slow_verbosity',
+    'long_query_time'
+);
+```
+
+??? example "Expected output"
+
+    ```{.text .no-copy}
+    +-----------------+-----------------+
+    | Variable_name   | Value           |
+    +-----------------+-----------------+
+    | thread_handling | pool-of-threads |
+    +-----------------+-----------------+
+
+    +---------------------------------+-------+
+    | Variable_name                   | Value |
+    +---------------------------------+-------+
+    | audit_log_filter_events_written | 42    |
+    +---------------------------------+-------+
+
+    +--------------+--------------------+------------------------------------+
+    | component_id | component_group_id | component_urn                      |
+    +--------------+--------------------+------------------------------------+
+    | 2            | 2                  | file://component_masking_functions |
+    +--------------+--------------------+------------------------------------+
+
+    +--------------------+----------+
+    | Variable_name      | Value    |
+    +--------------------+----------+
+    | log_slow_verbosity | standard |
+    | long_query_time    | 1.000000 |
+    | slow_query_log     | ON       |
+    +--------------------+----------+
+    ```
+
+    Event counts and component identifiers depend on the server.

mkdocs-base.yml

@@ -297,6 +297,7 @@ nav:
     - First five minutes: first-five-minutes.md
     - Sanity check (First five minutes): sanity-check.md
     - post-installation.md
+    - Production readiness and baseline configuration: production-readiness.md
     - binlogging-replication-improvements.md
     - AppArmor:
       - apparmor.md