Merge pull request #600 from percona/ps-10284-8.4

PS-10284 [DOCS] - add information about jemalloc in 8.4

Author: patrickbirch

docs/jemalloc-profiling.md

@@ -10,10 +10,10 @@ As root, customize jemalloc with the following flags:
 
 | Option            | Description                        |
 | ----------------- | ---------------------------------- |
-| –enable-stats     | Enables statistics-gathering ability  |
-| –enable-prof      | Enables heap profiling and the ability to detect leaks.|
+| --enable-stats     | Enables statistics-gathering ability  |
+| --enable-prof      | Enables heap profiling and the ability to detect leaks.|
 
-Using `LD_PRELOAD`. Build the library, configure the malloc configuration with the `prof:true` string, and then use `LD_PRELOAD` to  preload the `libjemalloc.so` library. The libprocess `MemoryProfiler` class detects the library automatically and enables the profiling support.
+Using `LD_PRELOAD`. Build the library, configure the malloc configuration with the `prof:true` string, and then use `LD_PRELOAD` to preload the `libjemalloc.so` library. Percona Server for MySQL detects jemalloc with profiling enabled automatically when properly configured.
 
 The following is an example of the required commands:
 
@@ -40,7 +40,7 @@ To enable jemalloc profiling in a MySQL client, run the following command:
 set global jemalloc_profiling=on;
 ```
 
-The malloc_stats_totals table returns the statistics, in bytes, of the memory usage. The command takes no parameters and returns the results as a table.
+The `malloc_stats_totals` table provides statistics, in bytes, of the memory usage.
 
 The following example commands display this result:
 
@@ -55,15 +55,15 @@ SELECT * FROM malloc_stats_totals;
 ??? example "Expected output"
 
     ```{.text .no-copy}
-    +----+------------+------------+------------+-------------+------------+
-    | id | ALLOCATION | MAPPED     | RESIDENT   | RETAINED    | METADATA   |
-    +----+------------+------------+------------+-------------+------------+
-    |  1 | 390977528  | 405291008  | 520167424  | 436813824   | 9933744    |
-    +----+------------+------------+------------+-------------+------------+
+    +------------+------------+------------+------------+-------------+------------+
+    | ALLOCATED  | ACTIVE     | MAPPED     | RESIDENT   | RETAINED    | METADATA   |
+    +------------+------------+------------+------------+-------------+------------+
+    | 390977528  | 391012352  | 405291008  | 520167424  | 436813824   | 9933744    |
+    +------------+------------+------------+------------+-------------+------------+
     1 row in set (0.00 sec)
     ```
 
-The [malloc_stats](#malloc_stats) table returns the cumulative totals, in bytes, of several statistics per type of arena. The command takes no parameters and returns the results as a table.
+The [malloc_stats](#malloc_stats) table provides cumulative totals, in bytes, of several statistics per allocation size type (small, large, and huge).
 
 The following example commands display this result:
 
@@ -156,15 +156,15 @@ The current stats for allocations. All measurements are in bytes.
 | Column Name          | Description                                |
 | -------------------- | ------------------------------------------------------------------- |
 | ALLOCATED            | The total amount the application allocated |
-| ACTIVE               | The total amount allocated by the application of active pages. A multiple of the page size and this value is greater than or equal to the stats.allocated value. The sum does not include allocator metadata pages and stats.arenas.<i>.pdirty or stats.arenas.<i>.pmuzzy. |
+| ACTIVE               | The total amount allocated by the application of active pages. A multiple of the page size and this value is greater than or equal to the stats.allocated value. The sum does not include allocator metadata pages and stats.arenas.[i].pdirty or stats.arenas.[i].pmuzzy. |
 | MAPPED               | The total amount in chunks that are mapped by the allocator in active extents. This value does not include inactive chunks. The value is at least as large as the stats.active and is a multiple of the chunk size. |
 | RESIDENT             | A maximum number the allocator has mapped in physically resident data pages. All allocator metadata pages and unused dirty pages are included in this value. Pages may not be physically resident if they correspond to demand-zeroed virtual memory that has not yet been touched. This value is a maximum rather than a precise value and is a multiple of the page size. The value is greater than the stats.active.|
 | RETAINED                       | The amount retained by the virtual memory mappings of the operating system. This value does not include any returned mappings. This type of memory, usually de-committed, untouched, or purged. The value is associated with physical memory and is excluded from mapped memory statistics.  |
 | METADATA                       | The total amount dedicated to metadata. This value contains the base allocations which are used for bootstrap-sensitive allocator metadata structures. Transparent huge pages usage is not included.  |
 
 ## malloc_stats
 
-The cumulative number of allocations requested or allocations returned for a running instance.
+The cumulative statistics for allocations and deallocations for a running instance.
 
 | Column Name           | Description                                         |
 | --------------------- | --------------------------------------------------- |
@@ -188,7 +188,7 @@ Description: This read-only variable returns `true` if jemalloc with profiling e
 
 * The environment variable `MALLOC_CONF` is set to `prof:true`.
 
-The following options are:
+Properties:
 
 * Scope: Global
 
@@ -200,7 +200,7 @@ The following options are:
 
 Description: Enables jemalloc profiling. The variable requires [jemalloc_detected](#jemalloc_detected).
 
-* Command Line: –jemalloc_profiling[=(OFF|ON)]
+* Command Line: --jemalloc_profiling[=(OFF|ON)]
 
 * Config File: Yes
 

docs/yum-download-rpm.md

@@ -49,7 +49,7 @@ The following example downloads *Percona Server for MySQL* {{release}} release `
         ```
 
 
-4. Install `jemalloc` with the following command, if needed:
+4. Install `jemalloc` with the following command, if needed. See [When to install jemalloc](#when-to-install-jemalloc) for guidance:
 
 	```{.bash data-prompt="$"}
 	$ wget https://repo.percona.com/yum/release/8/RPMS/x86_64/jemalloc-3.6.0-1.el8.x86_64.rpm
@@ -69,4 +69,32 @@ The following example downloads *Percona Server for MySQL* {{release}} release `
 
 	!!! note
 
-	    When installing packages manually, you must make sure to resolve all dependencies and install any missing packages yourself.
+	    When installing packages manually, you must make sure to resolve all dependencies and install any missing packages yourself.
+
+## When to install jemalloc
+
+`jemalloc` is an alternative memory allocator that can improve performance and reduce memory fragmentation in certain scenarios. Consider the following when deciding whether to install `jemalloc`:
+
+### Install jemalloc when:
+
+* You have high-concurrency workloads with many threads
+
+* You experience memory fragmentation issues that impact performance
+
+* You run multi-threaded applications that perform frequent memory allocation and deallocation
+
+* You want to use [memory profiling features](jemalloc-profiling.md) to investigate memory-related issues.
+
+* You observe performance degradation related to memory allocation in your current setup
+
+### Do not install jemalloc when:
+
+* Your current memory allocator (typically glibc malloc) performs adequately for your workload
+
+* You have single-threaded or low-concurrency workloads where jemalloc's benefits are minimal
+
+* You encounter compatibility issues with jemalloc in your environment
+
+* You need to debug memory issues that may be complicated by using an alternative allocator
+
+* Your system is already optimized and stable with the default memory allocator