Merge pull request #1861 from jasonrandrews/review

Review MongoDB Learning Path

Author: jasonrandrews

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

@@ -11,7 +11,7 @@ learning_objectives:
 - Measure and compare the performance of MongoDB on Arm versus other architectures with Yahoo Cloud Serving Benchmark (YCSB). 
 
 prerequisites:
-- An Arm based instance from a cloud service provider. 
+- An [Arm based instance](/learning-paths/servers-and-cloud-computing/csp/) from a cloud service provider.
 
 armips:
 - Neoverse

content/learning-paths/servers-and-cloud-computing/mongodb/automate_setup_pulumi.md

@@ -20,7 +20,7 @@ Install the python dependencies on your Ubuntu 22.04 machine:
 sudo apt update
 sudo apt install python-is-python3 -y
 sudo apt install python3-pip -y
-sudo apt install python3.10-venv
+sudo apt install python3.10-venv -y
 ```
 
 ## Install Pulumi 
@@ -41,7 +41,7 @@ git clone https://github.com/pbk8s/pulumi-ec2.git
 ```
 
 ## Build gatord
-You would also need the gatord binary for performance analysis. [gator](https://github.com/ARM-software/gator) is a target agent (daemon), part of Arm Streamline, a set of performance analysis tools. Use the following commands to build it from source.
+You will also need the gatord binary for performance analysis. [gator](https://github.com/ARM-software/gator) is a target agent (daemon), part of Arm Streamline, a set of performance analysis tools. Use the following commands to build it from source.
 
 ```bash
 git clone https://github.com/ARM-software/gator.git
@@ -65,14 +65,14 @@ cp build-native-gcc-rel/gatord ~/pulumi-ec2/
 ## Install awscli and set environment variables
 Use the [awscli](https://learn.arm.com/install-guides/aws-cli/) learning path to install the awscli. 
 
-Set the following environment variables on your local computer to connect to your AWS account
-```console
+Set the following environment variables on your local computer to connect to your AWS account:
+```bash
 export AWS_ACCESS_KEY_ID=<access-key-id>
 export AWS_SECRET_ACCESS_KEY=<secret-access-key>
 export AWS_SESSION_TOKEN=<session-token>
 ```
-Execute the following command to validate the credentials
-```console
+Execute the following command to validate the credentials:
+```bash
 aws sts get-caller-identity
 ```
 
@@ -134,7 +134,7 @@ subnet = aws.ec2.Subnet("p1-subnet",
     })
 ```
 
-Note: The security groups created by this script are lot less restrictive, to simplify the deployment process and to remove additional complexities. Please modify the ingress/egress rules as per your organizations' policy.
+Note: The security groups created by this script are a lot less restrictive, to simplify the deployment process and to remove additional complexities. Please modify the ingress/egress rules as per your organization's policy.
 
 ```python
 group = aws.ec2.SecurityGroup('p1-security-grouup',

content/learning-paths/servers-and-cloud-computing/mongodb/benchmark_mongodb-8.0.md

@@ -8,7 +8,7 @@ weight: 4 # (intro is 1), 2 is first, 3 is second, etc.
 layout: "learningpathall"
 ---
 
-To further measure the performance of MongoDB, you can run the [Yahoo Cloud Serving Benchmark](http://github.com/brianfrankcooper/YCSB).
+To further measure the performance of MongoDB, you can run the [Yahoo Cloud Serving Benchmark](https://github.com/brianfrankcooper/YCSB).
 
 YCSB is an open source project which provides the framework and common set of workloads to evaluate the performance of different "key-value" and "cloud" serving stores. Use the steps below to run YCSB to evaluate the performance of MongoDB running on 64-bit Arm machine.
 
@@ -22,9 +22,10 @@ Install the additional software:
   {{< tab header="Ubuntu" >}}
 sudo apt install -y maven make gcc
   {{< /tab >}}
-  {{< tab header="RHE/Amazon" >}}
+  {{< tab header="RHEL / Amazon Linux" >}}
 sudo yum check-update
-sudo yum install python2
+# Python 2 may not be available via yum on recent RHEL/Amazon Linux versions.
+# If needed, follow the manual installation steps below.
   {{< /tab >}}
 {{< /tabpane >}}
 
@@ -38,7 +39,7 @@ wget https://www.python.org/ftp/python/2.7.18/Python-2.7.18.tgz
 tar xvf Python-2.7.18.tgz
 cd Python-2.7.18
 ./configure --enable-optimizations
-make -j $nproc
+make -j $(nproc)
 sudo make altinstall
 sudo ln -s /usr/local/bin/python2.7 /usr/local/bin/python
 ```
@@ -68,14 +69,14 @@ To load and test the performance of loading data(INSERT) into default database `
 ```console
 ./bin/ycsb load mongodb -s -P workloads/workloada -p mongodb.url=mongodb://localhost:27017/ycsb?w=0 -threads 10
 ```
-The "-P" parameter is used to load property files. In this example, you used it load the workloada parameter file which sets the recordcount to 1000 in addition to other parameters. The "-threads" parameter indicates the number of threads and is set to 1 by default.
+The "-P" parameter is used to load property files. In this example, you used it load the workloada parameter file which sets the recordcount to 1000 in addition to other parameters. The "-threads" parameter indicates the number of client threads (default is 1); this example uses 10 threads.
 
 ## A simple Update/Read/Read Modify Write Test on MongoDB
 
 To test the performance of executing a workload which includes running UPDATE, Read Modify Write(RMW) and/or READ operations on the data using 10 threads for example, use the following command:
 
 ```console
-./bin/ycsb load mongodb -s -P workloads/workloada -p mongodb.url=mongodb://localhost:27017/ycsb?w=0
+./bin/ycsb run mongodb -s -P workloads/workloada -p mongodb.url=mongodb://localhost:27017/ycsb?w=0 -threads 10
 ```
 
 The workloads/workloada file in this example sets the following values `readproportion=0.5` and  `updateproportion=0.5` which means there is an even split between the number of READ and UPDATE operations performed. You can change the type of operations and the splits by providing your own workload parameter file.

content/learning-paths/servers-and-cloud-computing/mongodb/create_replica_set.md

@@ -8,33 +8,33 @@ weight: 3 # (intro is 1), 2 is first, 3 is second, etc.
 layout: "learningpathall"
 ---
 ## MongoDB test scenarios
-To test Mongodb you need two parts. A instance running the testing software([YCSB](/learning-paths/servers-and-cloud-computing/mongodb/benchmark_mongodb-8.0)). one or more instances running MongoDB in some configuration. The recommended MongoDB test setup is a three node relica set. These three nodes are of equal size with one instance being desigated as the primary node( the target for test traffic ) and the others as secondary nodes.
+To test MongoDB you need two parts. An instance running the testing software ([YCSB](/learning-paths/servers-and-cloud-computing/mongodb/benchmark_mongodb-8.0)). One or more instances running MongoDB in some configuration. The recommended MongoDB test setup is a three node replica set. These three nodes are of equal size with one instance being designated as the primary node (the target for test traffic) and the others as secondary nodes.
 
 ## What is a replica set?
 
 A replica set is a group of instances that maintain the same dataset. A replica set contains many nodes, but three nodes are the most common for testing.
 
 ## What node size should I use?
 
-The most common size for testing MongoDB is an 8 vCPU instance. You can test with any sized instance, but if you are looking for ideal testing conditions, 8 vCPUs is enough. Each node should have atleast 32GB of RAM.
+The most common size for testing MongoDB is an 8 vCPU instance. You can test with any sized instance, but if you are looking for ideal testing conditions, 8 vCPUs is enough. Each node should have at least 32GB of RAM.
 
-To achieve the best results, its recommended to keep the complete data set in memory. If you see disk access when running tests, increase the RAM size of your instances. Additional details about the recommended configuration are provided below.
+To achieve the best results, it's recommended to keep the complete data set in memory. If you see disk access when running tests, increase the RAM size of your instances. Additional details about the recommended configuration are provided below.
 
 ## Creating replica sets
 
-You can create replica sets of any size(two is the minimum). Three is recemmended but you can add as many as you like.
+You can create replica sets of any size (two is the minimum). Three is recommended but you can add as many as you like.
 
 ## Three node replica sets
 
-To creating a three node replica set, start by launching three [Arm based instance](/learning-paths/servers-and-cloud-computing/csp/) of equal size.
+To create a three node replica set, start by launching three Arm-based instances of equal size.
 
-[install](/learning-paths/servers-and-cloud-computing/mongodb/run_mongodb) Mongodb on all three instances.
+[Install](/learning-paths/servers-and-cloud-computing/mongodb/run_mongodb) MongoDB on all three instances.
 
-Once all three instances are up and running. Modify the service and configuration file for all instances.
+Once all three instances are up and running, modify the service and configuration file for all instances.
 
 ## Modify the MongoDB configuration
 
-Use a text editor to edit the file `/etc/mongodb.conf` and replace the contents of the file with the text below.
+Use a text editor to edit the file `/etc/mongod.conf` and replace the contents of the file with the text below.
 
 ```console
 # Configuration Options: https://docs.mongodb.org/manual/reference/configuration-options/
@@ -50,10 +50,10 @@ storage:
   engine: wiredTiger
   wiredTiger:
     engineConfig:
-      configString: "cache_size=16484MB" # 50% of your ram is recommened. Adding more helps depending on dataset.
+      configString: "cache_size=16484MB" # 50% of your ram is recommended. Adding more helps depending on dataset.
 
 replication:
-  replSetName: "rs0" # Name of your replicaset
+  replSetName: "rs0" # Name of your replica set
   oplogSizeMB: 5000
 
 # network interfaces
@@ -70,14 +70,14 @@ setParameter:
   tlsWithholdClientCertificate: true
 ```
 
-**Details of what all these mean is below:**
+**Details of what these mean are below:**
 
 **systemLog:** Contains locations and details of where logging should be contained.
 - **path:** Location for logging
 
-**storage:** Its recommended to run test within memory to get achieve the best performance. This contains details on the engine used and location of storage.
+**storage:** It's recommended to run test within memory to achieve the best performance. This contains details on the engine used and location of storage.
 - **engine:** Wiredtiger is used in this case. Using a disk will add latency.
-- **cache_size:** The minimum if using the recommend instance size is 50% of 32(16gb). But in testing using 18gb produced better results.
+- **cache_size:** The minimum if using the recommended instance size is 50% of 32(16gb). However, testing showed that using 18GB produced better results.
 
 **replication:** This is used for replica set setup.
 - **replSetName:** This is the name of the replica set.
@@ -91,15 +91,15 @@ setParameter:
 - **diagnosticDataCollectionDirectorySizeMB:** 400 is based on the docs.
 - **honorSystemUmask:** Sets read and write permissions only to the owner of new files
 - **lockCodeSegmentsInMemory:** Locks code into memory and prevents it from being swapped.
-- **suppressNoTLSPeerCertificateWarning:** allows clients to connect without a certificate. (Only for testing purposes)
-- **tlsWithholdClientCertificate:** Will not send the certification during communication. (Only for testing purposes)
+- **suppressNoTLSPeerCertificateWarning:** Allows clients to connect without a certificate. (Only for testing purposes)
+- **tlsWithholdClientCertificate:** Will not send the certificate during communication. (Only for testing purposes)
 
 If you want to use encryption you will need to add the security and keyFile to your configuration. As well as change some of the parameters in the `mongod.conf` file.
 
-Run this command to reload the new configurtion.
+Run this command to reload the new configuration.
 
-```
-sudo service mongod restart
+```bash
+sudo systemctl restart mongod
 ```
 
 ## Modify the MongoDB service
@@ -136,15 +136,15 @@ LimitNPROC=64000
 WantedBy=multi-user.target
 ```
 
-details on these can be found here: https://docs.mongodb.com/manual/reference/ulimit/#recommended-ulimit-settings
+Details on these can be found in the [documentation](https://docs.mongodb.com/manual/reference/ulimit/#recommended-ulimit-settings).
 
 Run this command to reload the service.
 
-```
-sudo ystemctl daemon-reload
+```bash
+sudo systemctl daemon-reload
 ```
 
-**Once all three instances are created and have mongodb installed, select one to be your primary node. The remaining instances will be secondary nodes.**
+**Once all three instances are created and have MongoDB installed, select one to be your primary node. The remaining instances will be secondary nodes.**
 
 ## Initialize the replica set
 
@@ -160,7 +160,7 @@ Connect to the primary node and run the following commands below.
 
 2. Initialize the replica set with the following command:
 
-    ```
+    ```bash
     mongosh --host $PRIMARY_NODE_IP:27017 <<EOF
     rs.initiate({
       _id: "rs0",

content/learning-paths/servers-and-cloud-computing/mongodb/perf_mongodb.md

@@ -18,7 +18,7 @@ Install the appropriate run-time environment to be able to use the performance t
   {{< tab header="Ubuntu" >}}
 sudo apt install default-jre default-jdk -y
 {{< /tab >}}
-{{< tab header="RHE/Amazon" >}}
+{{< tab header="RHEL/Amazon Linux" >}}
 sudo yum install java-17-openjdk
 {{< /tab >}}
 {{< /tabpane >}}
@@ -33,37 +33,41 @@ On your instance running MongoDB (you may need to start a new terminal), clone t
 git clone https://github.com/idealo/mongodb-performance-test.git
 ```
 
-Now `cd` into the project folder and execute the `jar` file:
+Now change into the project folder and execute the JAR file to see its usage instructions:
 
 ```bash { ret_code="1" }
 cd mongodb-performance-test
 java -jar ./latest-version/mongodb-performance-test.jar
 ```
-This will print a description of how to use the java application
+This will print a description of how to use the Java application.
 
 
 ## Run Insert test
 
 Run a test that inserts documents on `localhost:27017` (default).
 
-Use the following options:
-  * `-m` defines the test
-  * `-o` defines the number of iterations
-    * Alternatively, use `-d` to specify a time limit (in seconds)
-  * `-t` defines the number of threads
-  * `-db` defines the database to use
-  * `-c` defines how the data is collected.
-
-  For example:
+First, set an environment variable for the JAR file path for convenience:
 ```bash { cwd="./mongodb-performance-test" }
 export jarfile=./latest-version/mongodb-performance-test.jar
+```
+
+Use the following options:
+  * `-m` defines the test mode (e.g., `insert`, `update_one`).
+  * `-o` defines the number of operations (iterations).
+    * Alternatively, use `-d` to specify a duration limit (in seconds).
+  * `-t` defines the number of threads.
+  * `-db` defines the database to use.
+  * `-c` defines the collection to use.
+
+  For example, run an insert test for 1 million operations using 10 threads:
+```bash { cwd="./mongodb-performance-test" }
 java -jar $jarfile -m insert -o 1000000 -t 10 -db test -c perf
 ```
-As the test runs, the count will be printed periodically. It will increase until it reaches 1 million and then the test will end.
+As the test runs, the progress count will be printed periodically. It will increase until it reaches 1 million, and then the test will end.
 
 ## Run Update-one test
 
-Similarly, to run this test, updating one document per query using 10, 20 and finally 30 threads for 1 hour each run (3 hours in total) run the following command:
+Similarly, to run an update test (updating one document per query) using 10, 20, and finally 30 threads for 1 hour each (3 hours total), run the following command:
 
 ```console
 java -jar $jarfile -m update_one -d 3600 -t 10 20 30 -db test -c perf
@@ -73,7 +77,7 @@ For instructions on running any other tests or more details on the metrics repor
 
 ## View the results
 
-During each test, statistics over the last second are printed every second in the console. The following is the output from the end of running Insert test:
+During each test, statistics over the last second are printed to the console every second. After the test completes, final summary statistics are displayed. The following is example output from the end of the Insert test run:
 
 ``` output
 -- Timers ----------------------------------------------------------------------
@@ -96,4 +100,4 @@ stats-per-run-INSERT
             99.9% <= 15.59 milliseconds
 ```
 
-The metrics are also output to the `stats-per-second-[mode].csv` which is located in the same folder as the jar file. `[mode]` is  the executed mode(s), i.e. either `INSERT`, `UPDATE_ONE`, `UPDATE_MANY`, `COUNT_ONE`, `COUNT_MANY`, `ITERATE_ONE`, `ITERATE_MANY`, `DELETE_ONE` or `DELETE_MANY`.
+Detailed per-second metrics are also output to a CSV file named `stats-per-second-[mode].csv` (e.g., `stats-per-second-INSERT.csv`), located in the same folder as the JAR file. `[mode]` corresponds to the executed mode(s), such as `INSERT`, `UPDATE_ONE`, `DELETE_ONE`, etc.

content/learning-paths/servers-and-cloud-computing/mongodb/replica_set_testing.md

@@ -2,20 +2,17 @@
 # User change
 title: "Three node replica set testing with YCSB"
 
-
 weight: 5 # (intro is 1), 2 is first, 3 is second, etc.
 
 # Do not modify these elements
 layout: "learningpathall"
 ---
 
-talk about which one to get on and how to run tests and see output
-
 ## Recommended Tests on MongoDB
 
-The most common three tests are **95/5** (95% read and 5% update), **100/0** (100% read and 0% update) and **90/10** (90% read and 10% update). In real world testing its recommended to run a **95/5** test.
+The most common three tests are **95/5** (95% read and 5% update), **100/0** (100% read and 0% update) and **90/10** (90% read and 10% update). In real world testing it's recommended to run a **95/5** test.
 
-Once you have loaded the dataset, run the selected test for approximately **five** minutes. This will allow the system to warm up before you start collecting performance data. The goal is to reach a high cpu utilization( 90+% ). Adjusting the number of threads, operationscount and recordscount can help you achieve this. Examples below maybe need to be adjusted based on the instance type you selected.
+Once you have loaded the dataset, run the selected test for approximately **five** minutes. This will allow the system to warm up before you start collecting performance data. The goal is to reach a high CPU utilization (90+%). Adjusting the number of threads, operationscount and recordscount can help you achieve this. Examples below may need to be adjusted based on the instance type you selected.
 
 ## Load dataset
 
@@ -32,7 +29,7 @@ Once you have loaded the dataset, run the selected test for approximately **five
 ## Run 100/0 test:
 
 ```console
-./bin/ycsb run mongodb -s  -P workloads/workloadc  -p mongodb.url=mongodb://Localhost:27017 -p minfieldlength=50 -p compressibility=2 -p maxexecutiontime=120 -threads 64 -p operationcount=40000000 -p recordcount=20000000 -p requestdistribution=zipfian -p readproportion=1.0 -p updateproportion=0.0
+./bin/ycsb run mongodb -s  -P workloads/workloadc  -p mongodb.url=mongodb://localhost:27017 -p minfieldlength=50 -p compressibility=2 -p maxexecutiontime=120 -threads 64 -p operationcount=40000000 -p recordcount=20000000 -p requestdistribution=zipfian -p readproportion=1.0 -p updateproportion=0.0
 ```
 
 ## Run 90/10 test: