Merge pull request #9834 from cockroachdb/deployment-built-in-workloads

Use cockroach workload in deployment tutorials
cockroachdb · Feb 25, 2021 · 64d938b · 64d938b
2 parents b974404 + c1adbf6
commit 64d938b
Show file tree

Hide file tree

Showing 4 changed files with 202 additions and 70 deletions.
diff --git a/_includes/v20.2/prod-deployment/insecure-test-load-balancing.md b/_includes/v20.2/prod-deployment/insecure-test-load-balancing.md
@@ -1,45 +1,79 @@
-CockroachDB offers a pre-built `workload` binary for Linux that includes several load generators for simulating client traffic against your cluster. This step features CockroachDB's version of the [TPC-C](http://www.tpc.org/tpcc/) workload.
+CockroachDB comes with a number of [built-in workloads](cockroach-workload.html) for simulating client traffic. This step features CockroachDB's version of the [TPC-C](http://www.tpc.org/tpcc/) workload.
 
 {{site.data.alerts.callout_info}}
-Be sure that you have [set up an inbound rule](deploy-cockroachdb-on-aws-insecure.html#step-2-configure-your-network) that allows traffic from the application to the load balancer. In this case, you will run the sample workload on one of your instances. The traffic source for your inbound rule should therefore be the **internal (private)** IP address of that instance. To find this, open the Instances section of the Amazon EC2 console and click on the instance.
+Be sure that you have configured your network to allow traffic from the application to the load balancer. In this case, you will run the sample workload on one of your machines. The traffic source should therefore be the **internal (private)** IP address of that machine.
 {{site.data.alerts.end}}
 
-{{site.data.alerts.callout_success}}For comprehensive guidance on benchmarking CockroachDB with TPC-C, see our <a href="https://www.cockroachlabs.com/guides/cockroachdb-performance/">Performance Benchmarking white paper</a>.{{site.data.alerts.end}}
+{{site.data.alerts.callout_success}}
+For comprehensive guidance on benchmarking CockroachDB with TPC-C, see [Performance Benchmarking](performance-benchmarking-with-tpcc-local.html).
+{{site.data.alerts.end}}
 
 1. SSH to the machine where you want the run the sample TPC-C workload.
 
     This should be a machine that is not running a CockroachDB node.
 
-2. Download `workload` and make it executable:
+1. Download the [CockroachDB archive](https://binaries.cockroachdb.com/cockroach-{{ page.release_info.version }}.linux-amd64.tgz) for Linux, and extract the binary:
 
     {% include copy-clipboard.html %}
     ~~~ shell
-    $ wget https://edge-binaries.cockroachdb.com/cockroach/workload.LATEST ; chmod 755 workload.LATEST
+    $ wget -qO- https://binaries.cockroachdb.com/cockroach-{{ page.release_info.version }}.linux-amd64.tgz \
+    | tar  xvz
     ~~~
 
-3. Rename and copy `workload` into the `PATH`:
+1. Copy the binary into the `PATH`:
+
+    {% include copy-clipboard.html %}
+    ~~~ shell
+    $ cp -i cockroach-{{ page.release_info.version }}.linux-amd64/cockroach /usr/local/bin/
+    ~~~
+
+    If you get a permissions error, prefix the command with `sudo`.
+
+1. Use the [`cockroach workload`](cockroach-workload.html) command to load the initial schema and data, pointing it at the IP address of the load balancer:
 
     {% include copy-clipboard.html %}
     ~~~ shell
-    $ cp -i workload.LATEST /usr/local/bin/workload
+    $ cockroach workload init tpcc \
+    'postgresql://root@<IP ADDRESS OF LOAD BALANCER>:26257/tpcc?sslmode=disable'
     ~~~
 
-4. Start the TPC-C workload, pointing it at the IP address of the load balancer:
+1. Use the `cockroach workload` command to run the workload for 10 minutes:
 
     {% include copy-clipboard.html %}
     ~~~ shell
-    $ workload run tpcc \
-    --drop \
-    --init \
-    --duration=20m \
-    --tolerate-errors \
-    "postgresql://root@<IP ADDRESS OF LOAD BALANCER>:26257/tpcc?sslmode=disable"
+    $ cockroach workload run tpcc \
+    --duration=10m \
+    'postgresql://root@<IP ADDRESS OF LOAD BALANCER>:26257/tpcc?sslmode=disable'
     ~~~
 
-    This command runs the TPC-C workload against the cluster for 20 minutes, loading 1 "warehouse" of data initially and then issuing about 12 queries per minute via 10 "worker" threads. These workers share SQL connections since individual workers are idle for long periods of time between queries.
+    You'll see per-operation statistics print to standard output every second:
+
+    ~~~
+    _elapsed___errors__ops/sec(inst)___ops/sec(cum)__p50(ms)__p95(ms)__p99(ms)_pMax(ms)
+          1s        0         1443.4         1494.8      4.7      9.4     27.3     67.1 transfer
+          2s        0         1686.5         1590.9      4.7      8.1     15.2     28.3 transfer
+          3s        0         1735.7         1639.0      4.7      7.3     11.5     28.3 transfer
+          4s        0         1542.6         1614.9      5.0      8.9     12.1     21.0 transfer
+          5s        0         1695.9         1631.1      4.7      7.3     11.5     22.0 transfer
+          6s        0         1569.2         1620.8      5.0      8.4     11.5     15.7 transfer
+          7s        0         1614.6         1619.9      4.7      8.1     12.1     16.8 transfer
+          8s        0         1344.4         1585.6      5.8     10.0     15.2     31.5 transfer
+          9s        0         1351.9         1559.5      5.8     10.0     16.8     54.5 transfer
+         10s        0         1514.8         1555.0      5.2      8.1     12.1     16.8 transfer
+    ...
+    ~~~
+
+    After the specified duration (10 minutes in this case), the workload will stop and you'll see totals printed to standard output:
+
+    ~~~
+    _elapsed___errors_____ops(total)___ops/sec(cum)__avg(ms)__p50(ms)__p95(ms)__p99(ms)_pMax(ms)__result
+      600.0s        0         823902         1373.2      5.8      5.5     10.0     15.2    209.7
+    ~~~
 
-    {{site.data.alerts.callout_success}}For more <code>tpcc</code> options, use <code>workload run tpcc --help</code>. For details about other load generators included in <code>workload</code>, use <code>workload run --help</code>.
+    {{site.data.alerts.callout_success}}
+    For more `tpcc` options, use `cockroach workload run tpcc --help`. For details about other workloads built into the `cockroach` binary, use `cockroach workload --help`.
+    {{site.data.alerts.end}}
 
-4. To monitor the load generator's progress, open the [DB Console](ui-overview.html) by pointing a browser to the address in the `admin` field in the standard output of any node on startup.
+1. To monitor the load generator's progress, open the [DB Console](ui-overview.html) by pointing a browser to the address in the `admin` field in the standard output of any node on startup.
 
     Since the load generator is pointed at the load balancer, the connections will be evenly distributed across nodes. To verify this, click **Metrics** on the left, select the **SQL** dashboard, and then check the **SQL Connections** graph. You can use the **Graph** menu to filter the graph for specific nodes.
diff --git a/_includes/v20.2/prod-deployment/secure-test-load-balancing.md b/_includes/v20.2/prod-deployment/secure-test-load-balancing.md
@@ -1,47 +1,79 @@
-CockroachDB offers a pre-built `workload` binary for Linux that includes several load generators for simulating client traffic against your cluster. This step features CockroachDB's version of the [TPC-C](http://www.tpc.org/tpcc/) workload.
+CockroachDB comes with a number of [built-in workloads](cockroach-workload.html) for simulating client traffic. This step features CockroachDB's version of the [TPC-C](http://www.tpc.org/tpcc/) workload.
 
 {{site.data.alerts.callout_info}}
-Be sure that you have [set up an inbound rule](deploy-cockroachdb-on-aws-insecure.html#step-2-configure-your-network) that allows traffic from the application to the load balancer. In this case, you will run the sample workload on one of your instances. The traffic source for your inbound rule should therefore be the **internal (private)** IP address of that instance. To find this, open the Instances section of the Amazon EC2 console and click on the instance.
+Be sure that you have configured your network to allow traffic from the application to the load balancer. In this case, you will run the sample workload on one of your machines. The traffic source should therefore be the **internal (private)** IP address of that machine.
 {{site.data.alerts.end}}
 
-{{site.data.alerts.callout_success}}For comprehensive guidance on benchmarking CockroachDB with TPC-C, see our <a href="https://www.cockroachlabs.com/guides/cockroachdb-performance/">Performance Benchmarking white paper</a>.{{site.data.alerts.end}}
+{{site.data.alerts.callout_success}}
+For comprehensive guidance on benchmarking CockroachDB with TPC-C, see [Performance Benchmarking](performance-benchmarking-with-tpcc-local.html).
+{{site.data.alerts.end}}
 
 1. SSH to the machine where you want to run the sample TPC-C workload.
 
     This should be a machine that is not running a CockroachDB node, and it should already have a `certs` directory containing `ca.crt`, `client.root.crt`, and `client.root.key` files.
 
-2. Download `workload` and make it executable:
+1. Download the [CockroachDB archive](https://binaries.cockroachdb.com/cockroach-{{ page.release_info.version }}.linux-amd64.tgz) for Linux, and extract the binary:
 
     {% include copy-clipboard.html %}
     ~~~ shell
-    $ wget https://edge-binaries.cockroachdb.com/cockroach/workload.LATEST ; chmod 755 workload.LATEST
+    $ wget -qO- https://binaries.cockroachdb.com/cockroach-{{ page.release_info.version }}.linux-amd64.tgz \
+    | tar  xvz
     ~~~
 
-3. Rename and copy `workload` into the `PATH`:
+1. Copy the binary into the `PATH`:
+
+    {% include copy-clipboard.html %}
+    ~~~ shell
+    $ cp -i cockroach-{{ page.release_info.version }}.linux-amd64/cockroach /usr/local/bin/
+    ~~~
+
+    If you get a permissions error, prefix the command with `sudo`.
+
+1. Use the [`cockroach workload`](cockroach-workload.html) command to load the initial schema and data, pointing it at the IP address of the load balancer:
 
     {% include copy-clipboard.html %}
     ~~~ shell
-    $ cp -i workload.LATEST /usr/local/bin/workload
+    $ cockroach workload init tpcc \
+    'postgresql://root@<IP ADDRESS OF LOAD BALANCER>:26257/tpcc?sslmode=verify-full&sslrootcert=certs/ca.crt&sslcert=certs/client.root.crt&sslkey=certs/client.root.key'
     ~~~
 
-4. Start the TPC-C workload, pointing it at the IP address of the load balancer and the location of the `ca.crt`, `client.root.crt`, and `client.root.key` files:
+1. Use the `cockroach workload` command to run the workload for 10 minutes:
 
     {% include copy-clipboard.html %}
     ~~~ shell
-    $ workload run tpcc \
-    --drop \
-    --init \
-    --duration=20m \
-    --tolerate-errors \
-    "postgresql://root@<IP ADDRESS OF LOAD BALANCER>:26257/tpcc?sslmode=verify-full&sslrootcert=certs/ca.crt&sslcert=certs/client.root.crt&sslkey=certs/client.root.key"
+    $ cockroach workload run tpcc \
+    --duration=10m \
+    'postgresql://root@<IP ADDRESS OF LOAD BALANCER>:26257/tpcc?sslmode=verify-full&sslrootcert=certs/ca.crt&sslcert=certs/client.root.crt&sslkey=certs/client.root.key'
     ~~~
 
-    This command runs the TPC-C workload against the cluster for 20 minutes, loading 1 "warehouse" of data initially and then issuing about 12 queries per minute via 10 "worker" threads. These workers share SQL connections since individual workers are idle for long periods of time between queries.
+    You'll see per-operation statistics print to standard output every second:
 
-    {{site.data.alerts.callout_success}}For more <code>tpcc</code> options, use <code>workload run tpcc --help</code>. For details about other load generators included in <code>workload</code>, use <code>workload run --help</code>.
+    ~~~
+    _elapsed___errors__ops/sec(inst)___ops/sec(cum)__p50(ms)__p95(ms)__p99(ms)_pMax(ms)
+          1s        0         1443.4         1494.8      4.7      9.4     27.3     67.1 transfer
+          2s        0         1686.5         1590.9      4.7      8.1     15.2     28.3 transfer
+          3s        0         1735.7         1639.0      4.7      7.3     11.5     28.3 transfer
+          4s        0         1542.6         1614.9      5.0      8.9     12.1     21.0 transfer
+          5s        0         1695.9         1631.1      4.7      7.3     11.5     22.0 transfer
+          6s        0         1569.2         1620.8      5.0      8.4     11.5     15.7 transfer
+          7s        0         1614.6         1619.9      4.7      8.1     12.1     16.8 transfer
+          8s        0         1344.4         1585.6      5.8     10.0     15.2     31.5 transfer
+          9s        0         1351.9         1559.5      5.8     10.0     16.8     54.5 transfer
+         10s        0         1514.8         1555.0      5.2      8.1     12.1     16.8 transfer
+    ...
+    ~~~
+
+    After the specified duration (10 minutes in this case), the workload will stop and you'll see totals printed to standard output:
+
+    ~~~
+    _elapsed___errors_____ops(total)___ops/sec(cum)__avg(ms)__p50(ms)__p95(ms)__p99(ms)_pMax(ms)__result
+      600.0s        0         823902         1373.2      5.8      5.5     10.0     15.2    209.7
+    ~~~
 
-5. To monitor the load generator's progress, open the [DB Console](ui-overview.html) by pointing a browser to the address in the `admin` field in the standard output of any node on startup.
+    {{site.data.alerts.callout_success}}
+    For more `tpcc` options, use `cockroach workload run tpcc --help`. For details about other workloads built into the `cockroach` binary, use `cockroach workload --help`.
+    {{site.data.alerts.end}}
 
-    For each user who should have access to the DB Console for a secure cluster, [create a user with a password](create-user.html#create-a-user-with-a-password) and [assign them to an `admin` role if necessary](ui-overview.html#db-console-access). On accessing the DB Console, the users will see a Login screen, where they will need to enter their usernames and passwords.
+1. To monitor the load generator's progress, open the [DB Console](ui-overview.html) by pointing a browser to the address in the `admin` field in the standard output of any node on startup.
 
     Since the load generator is pointed at the load balancer, the connections will be evenly distributed across nodes. To verify this, click **Metrics** on the left, select the **SQL** dashboard, and then check the **SQL Connections** graph. You can use the **Graph** menu to filter the graph for specific nodes.