first pass edits

Author: anupras-mohapatra-arm

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

@@ -15,7 +15,7 @@ learning_objectives:
 prerequisites:
     - 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/).
+    - If you don't already have an NGINX setup, see [Learn how to deploy NGINX](/learning-paths/servers-and-cloud-computing/nginx/).
 
 author: Julio Suarez
 

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

@@ -1,5 +1,5 @@
 ---
-title: "Measure NGINX tuning impact"
+title: Measure the impact of NGINX tuning
 description: Learn how to approach NGINX performance tuning as a measurement-driven process and compare baseline results with tuned results.
 weight: 2
 layout: "learningpathall"
@@ -15,7 +15,7 @@ Whatever method you use, keep the measurements repeatable. Record the system con
 
 ## Why tune NGINX
 
-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.
+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. By tuning, you can 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.
 
@@ -26,3 +26,9 @@ The following example shows `wrk` throughput before and after tuning for an NGIN
 ![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.
+
+## What you've learned and what's next
+
+You've now learned why tuning NGINX is useful and reviewed an example benchmark demonstrating improvement in `wrk` throughput after tuning. 
+
+Next, you'll learn about kernel, compiler, and library optimizations. 

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

@@ -1,5 +1,5 @@
 ---
-title: "Kernel, compiler, and libraries"
+title: Tune kernel, compiler, and library settings for performance
 weight: 3
 layout: "learningpathall"
 ---
@@ -34,55 +34,65 @@ sudo sysctl -w net.ipv4.tcp_wmem="4096 8388608 8388608"
 
 These values are intentionally large. Size them for your expected connection rate, request pattern, and available memory.
 
-* `net.core.somaxconn`:
-  * 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 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 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 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 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 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 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.
+- `net.core.somaxconn`:
+  - 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`:
+  -  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 set a value for this parameter.
+- `net.core.wmem_max`:
+  - 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 set a value for this parameter.
+- `net.ipv4.tcp_max_syn_backlog`:
+  - 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`:
+  - 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`:
+  - 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 set a value for this parameter.
+- `net.ipv4.tcp_wmem`:
+  - 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 set 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.
+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. For more information about these flags, see 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.
 
 When you configure an NGINX source build, pass compiler flags with the `--with-cc-opt` option.
 
-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.
+To understand how to configure an NGINX build, see 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.
 
 ## 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.
 
 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.
 
-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.
+You can also build NGINX 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.
 
 Run `nginx -V` to check the TLS library information and configure options used by your NGINX build.
 
 ## 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 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.
+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. 
+
+To learn how to build PCRE with NGINX from source, see the NGINX [installation instructions](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-open-source/#compiling-and-installing-from-source).
 
 ## 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. 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.
+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.
+
+ To learn how to build zlib with NGINX from source, see the NGINX [installation instructions](https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-open-source/#compiling-and-installing-from-source).
+
+## What you've learned and what's next
+
+You've now learned about different kernel, compiler, and library optimizations that you can make to tune NGINX performance.
+
+Next, you'll review the configuration for a static file server and learn about optimizations that you can make.

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

@@ -1,20 +1,22 @@
 ---
-title: "Test optimizations"
+title: Test NGINX optimizations
 weight: 6
 layout: "learningpathall"
 ---
 
-## Test NGINX optimizations
+## Use wrk to test NGINX
 
 You can skip this section if you already have a performance test method for your NGINX deployment.
 
-This section presents one method for testing NGINX with `wrk`. Use it as a starting point if you don't already have an established load test strategy. To understand the impact of tuning on your deployment, use a workload that reflects your request pattern, response size, TLS behavior, concurrency, and upstream service behavior.
+One method for testing NGINX is with `wrk`. Use this method as a starting point if you don't already have an established load test strategy. 
 
-## About wrk
+To understand the impact of tuning on your deployment, use a workload that reflects your request pattern, response size, TLS behavior, concurrency, and upstream service behavior.
+
+### About wrk
 
 [`wrk`](https://github.com/wg/wrk) is an HTTP load test tool that lets you configure the number of threads, open connections, and test duration. It reports throughput and latency statistics. Another option is [`h2load`](https://nghttp2.org/documentation/h2load-howto.html), which is useful when you want to test HTTP/2 behavior or prefer the `nghttp2` toolchain.
 
-## Install wrk
+### Install wrk
 
 You can install `wrk` by cloning the source and using `make`.
 
@@ -35,15 +37,15 @@ cd wrk
 make
 ```
 
-## Example load test setup
+### Example load test setup
 
 The following diagram shows a typical multi-node test setup. The load generator runs `wrk`. The instance under test runs the reverse proxy or API gateway. The file servers act as upstream servers for the reverse proxy or API gateway.
 
 You can also run `wrk` directly against NGINX file servers, or run `wrk` on the same node as NGINX. Choose a setup that reflects your deployment and avoids making the load generator the bottleneck.
 
 ![Diagram showing a load generator running wrk against an NGINX reverse proxy with upstream NGINX file servers.#center](exampletestsetup.png "Example NGINX load test setup")
 
-## Running a wrk test
+### Run a wrk test
 
 The NGINX file servers need files to serve. If you are using the configuration files discussed in [Tune a static file server](/learning-paths/servers-and-cloud-computing/nginx_tune/tune_static_file_server/) or [Tune a reverse proxy or API gateway](/learning-paths/servers-and-cloud-computing/nginx_tune/tune_revprox_and_apigw/), run the following commands on each file server to create sample files. You do not need to create these files on reverse proxy or API gateway nodes because they do not serve files directly.
 
@@ -79,3 +81,9 @@ The following sample command tests an API gateway path:
 ```
 
 The API gateway shown in [Tune a reverse proxy or API gateway](/learning-paths/servers-and-cloud-computing/nginx_tune/tune_revprox_and_apigw/) rewrites `api_old` to `api_new`. This is why the sample files are copied into `/usr/share/nginx/html/api_new` as well as the document root on the file servers.
+
+## What you've accomplished 
+
+You've now used `wrk` to run an NGINX performance test.
+
+You can use the guidance in this Learning Path to optimize the performance of your NGINX workloads on Arm-based platforms.