Merge pull request #3441 from jsrz/nginx-tuning-lp-refresh

NGINX Tuning LP Refresh

Author: jasonrandrews

content/learning-paths/servers-and-cloud-computing/nginx_tune/_index.md

@@ -1,20 +1,21 @@
 ---
-title: Learn how to tune Nginx
+title: Tune NGINX performance on Arm-based platforms
+description: Learn how to tune NGINX, Linux network settings, and supporting libraries to improve web server, reverse proxy, and API gateway performance on Arm-based platforms.
 
 minutes_to_complete: 60
 
-who_is_this_for: This is an advanced topic for software developers who want to use Nginx on Arm.
+who_is_this_for: This Learning Path is for software developers and system administrators who want to optimize NGINX performance on Arm-based platforms.
 
 learning_objectives:
-    - Describe how kernel parameters can impact Nginx performance.
-    - Describe how compilers and libraries can impact Nginx performance.
-    - Tune a Nginx file server configuration file.
-    - Tune a Nginx Reverse Proxy and API Gateway configuration file.
-    - Describe how to test Nginx performance.
+    - Configure Linux network settings that affect NGINX connection handling.
+    - Tune NGINX directives for static file server, reverse proxy, and API gateway workloads.
+    - Evaluate compiler, OpenSSL, PCRE, and zlib choices that can affect NGINX performance.
+    - Measure NGINX performance before and after tuning.
 
 prerequisites:
-    - A cloud or bare-metal installation of a Nginx file server or load balancer.
-    - If you do not already have a Nginx setup, a review of [Learn how to deploy Nginx](/learning-paths/servers-and-cloud-computing/nginx/).
+    - A cloud or bare-metal installation of an NGINX file server, reverse proxy, or API gateway.
+    - A repeatable HTTP workload or load test that you can run before and after tuning.
+    - If you do not already have an NGINX setup, review [Learn how to deploy NGINX](/learning-paths/servers-and-cloud-computing/nginx/).
 
 author: Julio Suarez
 
@@ -33,26 +34,42 @@ cloud_service_providers:
 armips:
     - Neoverse
 tools_software_languages:
-    - NGINX    
+    - NGINX
     - Runbook
 
 operatingsystems:
     - Linux
 
+test_images:
+    - ubuntu:latest
+test_link: null
+test_maintenance: true
+
 further_reading:
     - resource:
-        title: Nginx Documentation
+        title: NGINX documentation
         link: https://nginx.org/en/docs/
         type: documentation
     - resource:
-        title: Nginx Admin Guide
+        title: NGINX directive index
+        link: https://nginx.org/en/docs/dirindex.html
+        type: documentation
+    - resource:
+        title: NGINX variable index
+        link: https://nginx.org/en/docs/varindex.html
+        type: documentation
+    - resource:
+        title: NGINX Admin Guide
         link: https://docs.nginx.com/nginx/admin-guide/
         type: documentation
+    - resource:
+        title: h2load HOW-TO
+        link: https://nghttp2.org/documentation/h2load-howto.html
+        type: documentation
 
 ### FIXED, DO NOT MODIFY
 # ================================================================================
 weight: 1                       # _index.md always has weight of 1 to order correctly
 layout: "learningpathall"       # All files under learning paths have this same wrapper
 learning_path_main_page: "yes"  # This should be surfaced when looking for related content. Only set for _index.md of learning path content.
 ---
-

content/learning-paths/servers-and-cloud-computing/nginx_tune/before_and_after.md

@@ -1,17 +1,28 @@
 ---
-title: "Before and after tuning Nginx"
+title: "Measure NGINX tuning impact"
+description: Learn how to approach NGINX performance tuning as a measurement-driven process and compare baseline results with tuned results.
 weight: 2
 layout: "learningpathall"
 ---
 
-##  Importance of tuning
+## About performance tuning
 
-Application tuning allows you to gain performance without scaling your deployment up (bigger machines/nodes) or out (more machines/nodes). This gained performance can either be used, or traded for cost savings by reducing the amount of compute resources provisioned. The graphs below shows the performance gains of an Nginx file server, Reverse Proxy, and API Gateway when they are tuned.
+Performance tuning is most useful when you treat it as a measurement process, not a fixed checklist. You can tune by changing one parameter at a time, running a designed experiment, comparing profiles, or using automation and AI-assisted tools to explore a larger configuration space.
 
-![File Server Before and after Tuning](beforeandafterfileserver.png)
+There isn't a universal set of tuning parameters that works best for every application. The right settings depend on the request profile, response size, TLS configuration, cache behavior, upstream service behavior, network path, software version, system architecture, operating system, and other application-specific factors.
 
-![Reverse Proxy Before and after Tuning](beforeandafterrp.png)
+Whatever method you use, keep the measurements repeatable. Record the system configuration, workload, software versions, and tuning parameters so you can identify which changes improved performance and which changes had little effect.
 
-![API Gateway Before and after Tuning](beforeandafterapigw.png)
+## Why tune NGINX
 
-Requirements vary based on the use case. In the example shown above, the AWS m7g.2xlarge instance type could be down sized to a m7g.xlarge to gain cost savings.
+NGINX performance can be limited by connection handling, kernel network settings, TLS processing, file I/O, upstream connection reuse, cache behavior, logging, or regular expression processing. Tuning helps you use the available compute, memory, storage, and network resources more efficiently.
+
+Improved performance can give you higher throughput, lower latency, or better cost efficiency. A tuned configuration can increase capacity on the same system, or help you meet the same performance target with fewer compute resources.
+
+## Example performance result
+
+The following example shows `wrk` throughput before and after tuning for an NGINX API gateway on an Arm Neoverse V3 system. The result is normalized to the out-of-box configuration, so `1.00` represents the baseline.
+
+![Bar chart comparing normalized NGINX API gateway wrk throughput before and after tuning. The out-of-box configuration is normalized to 1.00, and the tuned configuration reaches 1.13, showing about 13% higher RPS after tuning.#center](nginxoobvstuned.png "NGINX API gateway throughput before and after tuning")
+
+This result is an example, not a guaranteed improvement for every workload. Your results depend on the NGINX version, request rate, response size, TLS settings, client concurrency, upstream services, network configuration, and system resources.

content/learning-paths/servers-and-cloud-computing/nginx_tune/beforeandafterapigw.png

@@ -4,81 +4,85 @@ weight: 3
 layout: "learningpathall"
 ---
 
-##  Kernel configuration
+## Kernel configuration
 
-The profile of requests made by clients will differ based on the use case. This means there is no one size fits all set of tuning parameters for Nginx. Use the information below as general guidance to tune Nginx.
+NGINX tuning doesn't stop at `nginx.conf`. Foundational settings such as kernel network queues, socket buffers, compiler choices, and TLS libraries can affect throughput and latency. Treat these settings as part of the same measurement process you use for NGINX directives.
 
-### Linux Network Stack
+### Linux network stack
 
-The Linux Network stack settings can be changed in the `/etc/sysctl.conf` file, or by using the `sysctl` command.
+You can change Linux network stack settings in `/etc/sysctl.conf`, or by using the `sysctl` command.
 
-Documentation on each of the parameters discussed below can be found in the [admin-guide](https://github.com/torvalds/linux/blob/master/Documentation/admin-guide/sysctl/net.rst) and [networking](https://github.com/torvalds/linux/blob/master/Documentation/networking/ip-sysctl.rst) documentation within the Linux source.
+For details about these parameters, see the Linux kernel [sysctl network admin guide](https://github.com/torvalds/linux/blob/master/Documentation/admin-guide/sysctl/net.rst) and [IP sysctl documentation](https://github.com/torvalds/linux/blob/master/Documentation/networking/ip-sysctl.rst).
 
-Run the command below to list all kernel parameters.
+Run the following command to list all kernel parameters:
 
 ```bash
 sudo sysctl -a
 ```
 
-Shown below are the network stack settings used for performance testing.
+The following commands show example network settings for high-connection workloads:
 
-```
+```bash
 sudo sysctl -w net.core.somaxconn=65535
-sudo sysctl -w net.core.rmem_max=8388607
-sudo sysctl -w net.core.wmem_max=8388607
+sudo sysctl -w net.core.rmem_max=8388608
+sudo sysctl -w net.core.wmem_max=8388608
 sudo sysctl -w net.ipv4.tcp_max_syn_backlog=65535
 sudo sysctl -w net.ipv4.ip_local_port_range="1024 65535"
-sudo sysctl -w net.ipv4.tcp_rmem="4096 8338607 8338607"
-sudo sysctl -w net.ipv4.tcp_wmem="4096 8338607 8338607"
+sudo sysctl -w net.ipv4.tcp_rmem="4096 8388608 8388608"
+sudo sysctl -w net.ipv4.tcp_wmem="4096 8388608 8388608"
 ```
 
-These settings open up the network stack to make sure it is not a bottleneck.
+These values are intentionally large. Size them for your expected connection rate, request pattern, and available memory.
 
 * `net.core.somaxconn`:
-  * This setting is used to select the maximum number of connections the kernel will allow.
-  * If the Nginx server is expected to support a large number of clients, it may be helpful to increase this parameter.
-  * A value of 65535 is probably excessively large for production. In practice, this just needs to be large enough to support the peak number of connections that will be made.
+  * This setting selects the maximum number of queued connections the kernel allows.
+  * If the NGINX server needs to support a large number of clients, it can be helpful to increase this parameter.
+  * A value of 65535 is likely excessive for many deployments. In practice, this value needs to be large enough to support the peak number of queued connections.
 * `net.core.rmem_max`:
-  * This setting is used to set the maximum read socket buffer size.
-  * 8MB is likely more than enough for most use cases.
-  * Socket buffer utilization can be checked with a tool like `ss` (Socket Statistics). The information provided by this tool can be used to select a value for this parameter.
+  * This setting selects the maximum read socket buffer size.
+  * `8 MiB` is likely more than enough for most use cases.
+  * Use a tool such as `ss` to check socket buffer utilization and select a value for this parameter.
 * `net.core.wmem_max`:
-  * This setting is used to set the maximum write socket buffer size.
-  * 8MB is likely more than enough for most use cases.
-  * Socket buffer utilization can be checked with a tool like `ss` (Socket Statistics). The information provided by this tool can be used to select a value for this parameter.
+  * This setting selects the maximum write socket buffer size.
+  * `8 MiB` is likely more than enough for most use cases.
+  * Use a tool such as `ss` to check socket buffer utilization and select a value for this parameter.
 * `net.ipv4.tcp_max_syn_backlog`:
-  * This setting is used to select the maximum number of connection requests that are pending but not established yet.
-  * A value of 65535 is probably excessively large for production. In practice, this just needs to be large enough to support the peak number of connection requests that will be made.
+  * This setting selects the maximum number of connection requests that are pending but not established yet.
+  * A value of 65535 is likely excessive for many deployments. In practice, this value needs to be large enough to support the peak number of pending connection requests.
 * `net.ipv4.ip_local_port_range`:
-  * This setting is used to select the range of ports the kernel can use.
-  * The port range is expanded above. Typically the default range is sufficient.
+  * This setting selects the range of local ports the kernel can use.
+  * The example expands the port range. The default range is sufficient for many deployments.
 * `net.ipv4.tcp_rmem`:
-  * This setting is used to set the maximum TCP read socket buffer size.
-  * 8MB is likely more than enough for most use cases.
-  * TCP buffer utilization can be checked with a tool like `ss` (Socket Statistics). The information provided by this tool can be used to select a value for this parameter.
+  * This setting selects the TCP read socket buffer size.
+  * `8 MiB` is likely more than enough for most use cases.
+  * Use a tool such as `ss` to check TCP buffer utilization and select a value for this parameter.
 * `net.ipv4.tcp_wmem`:
-  * This setting is used to set the maximum TCP write socket buffer size.
-  * 8MB is likely more than enough for most use cases.
-  * TCP buffer utilization can be checked with a tool like `ss` (Socket Statistics). The information provided by this tool can be used to select a value for this parameter.
+  * This setting selects the TCP write socket buffer size.
+  * `8 MiB` is likely more than enough for most use cases.
+  * Use a tool such as `ss` to check TCP buffer utilization and select a value for this parameter.
+
+## Compiler considerations
+
+If you build NGINX from source, the compiler version and optimization flags can affect performance. Use a recent version of GCC, and consider flags such as `-mcpu` and `-flto` for additional optimization. These flags are explained in the [Migrating C/C++ applications](/learning-paths/servers-and-cloud-computing/migration/c/) section of the [Migrating applications to Arm servers](/learning-paths/servers-and-cloud-computing/migration/) Learning Path.
 
-##  Compiler Considerations
+When you configure an NGINX source build, pass compiler flags with the `--with-cc-opt` option.
 
-The easiest way to gain performance is to use the latest version of GCC. Aside from that, the flag `-mcpu` can be used to potentially gain additional performance. Usage of this flag is explained in the [Migrating C/C++ applications](/learning-paths/servers-and-cloud-computing/migration/c/) section of the [Migrating applications to Arm servers](/learning-paths/servers-and-cloud-computing/migration/) learning path.
+To understand how to configure an NGINX build, review the [build NGINX from source](/learning-paths/servers-and-cloud-computing/nginx/build_from_source/) section of the [Learn how to deploy NGINX](/learning-paths/servers-and-cloud-computing/nginx/) Learning Path.
 
-If you need to understand how to configure a build of Nginx. Please review the [build Nginx from source](/learning-paths/servers-and-cloud-computing/nginx/build_from_source/) section of the [Learn to deploy Nginx learning path](/learning-paths/servers-and-cloud-computing/nginx/).
+## OpenSSL
 
-##  OpenSSL
+NGINX relies on [OpenSSL](https://www.openssl.org/) for cryptographic operations. The OpenSSL version, GCC version, and compiler switches used to build OpenSSL can affect TLS performance. The Linux distribution default version of OpenSSL is sufficient for many deployments.
 
-Nginx relies on [OpenSSL](https://www.openssl.org/) for cryptographic operations. Thus, the version of OpenSSL used with Nginx (and the GCC version and switches used to compile it) can impact performance. Typically using the Linux distribution default version of OpenSSL is sufficient.
+Newer versions of OpenSSL might improve performance for some TLS workloads. To use a specific OpenSSL source tree, pass the `--with-openssl` switch when configuring the NGINX build. Point this switch to the directory that contains the source code of the OpenSSL version you want NGINX to link to. You can also use `--with-openssl-opt` to pass options to the OpenSSL build.
 
-However, it is possible to use newer versions of OpenSSL which could yield performance improvements. This is achieved by using the `--with-openssl` switch when configuring the Nginx build. Point this switch to the directory that contains the source code of the version of OpenSSL you'd like to have Nginx link to. The Nginx build system takes care of the rest. There is also a `--with-openssl-opt` switch which allows you to add options to the build for OpenSSL.
+NGINX can also be built with OpenSSL-compatible alternatives for some use cases. For example, the NGINX [QUIC and HTTP/3 documentation](https://nginx.org/en/docs/quic.html) shows how to configure NGINX with BoringSSL, LibreSSL, or QuicTLS. Consider this when you have a specific TLS or QUIC reason to evaluate another library, and measure the result with your workload.
 
-The version of OpenSSL Nginx is using can be verified by running the command `nginx -V`.
+Run `nginx -V` to check the TLS library information and configure options used by your NGINX build.
 
-##  Perl Compatible Regular Expressions (PCRE)
+## Perl Compatible Regular Expressions (PCRE)
 
-Nginx relies on [PCRE](https://www.pcre.org/) for regular expression processing. One scenario where regular expressions are used is for an API Gateway. Typically, using the Linux distribution default version of PCRE is sufficient. However, it is possible to use a newer version of PCRE to potentially gain performance. The Nginx [installation instructions](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-open-source/#compiling-and-installing-from-source) explain how to build the latest version of PCRE if this is something you want to explore.
+NGINX relies on [PCRE](https://www.pcre.org/) for regular expression processing. One scenario where regular expressions are used is an API gateway path rewrite. The Linux distribution default version of PCRE is sufficient for many deployments. A newer version of PCRE might improve performance for regular expression-heavy configurations. The NGINX [installation instructions](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-open-source/#compiling-and-installing-from-source) explain how to build PCRE with NGINX from source.
 
-##  zlib for HTTP response compression
+## zlib for HTTP response compression
 
-Nginx relies on [zlib](https://zlib.net/) for HTTP response compression (when the `ngx_http_gzip_module` directives are used). Typically, using the Linux distribution default version of zlib is sufficient. However, it is possible to use a newer version of zlib to potentially gain performance. The Nginx [installation instructions](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-open-source/#compiling-and-installing-from-source) explain how to build the latest version of zlib if this is something you want to explore.
+NGINX relies on [zlib](https://zlib.net/) for HTTP response compression when the `ngx_http_gzip_module` directives are used. The Linux distribution default version of zlib is sufficient for many deployments. A newer version of zlib might improve performance for compression-heavy workloads. The NGINX [installation instructions](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-open-source/#compiling-and-installing-from-source) explain how to build zlib with NGINX from source.