additional docs

activitytype-cql/src/main/java/io/nosqlbench/activitytype/cql/statements/rowoperators/SaveGlobalVars.java

@@ -8,6 +8,10 @@ import io.nosqlbench.virtdata.library.basics.core.threadstate.SharedState;
 import java.util.List;
 import java.util.concurrent.ConcurrentHashMap;
 
+/**
+ * Stores the current row into the global object map. Key names are set from the field names. Null values are stored
+ * as empty strings.
+ */
 public class SaveGlobalVars implements RowCycleOperator {
 
     ConcurrentHashMap<String, Object> gl_vars = SharedState.gl_ObjectMap;

activitytype-cql/src/main/java/io/nosqlbench/activitytype/cql/statements/rowoperators/SaveThreadRows.java

@@ -6,6 +6,9 @@ import io.nosqlbench.activitytype.cql.statements.rsoperators.PerThreadCQLData;
 
 import java.util.LinkedList;
 
+/**
+ * Adds the current row to the per-thread row cache.
+ */
 public class SaveThreadRows implements RowCycleOperator {
 
     @Override

activitytype-cql/src/main/java/io/nosqlbench/activitytype/cql/statements/rowoperators/SaveThreadVars.java

@@ -8,6 +8,10 @@ import io.nosqlbench.virtdata.library.basics.core.threadstate.SharedState;
 import java.util.HashMap;
 import java.util.List;
 
+/**
+ * Saves all the values in this row to the thread-local object map,
+ * with the field names as keys.
+ */
 public class SaveThreadVars implements RowCycleOperator {
 
     ThreadLocal<HashMap<String, Object>> tl_objectMap = SharedState.tl_ObjectMap;

activitytype-cql/src/main/java/io/nosqlbench/activitytype/cql/statements/rsoperators/AssertSingleRowResultSet.java

@@ -5,6 +5,9 @@ import com.datastax.driver.core.Statement;
 import io.nosqlbench.activitytype.cql.api.ResultSetCycleOperator;
 import io.nosqlbench.activitytype.cql.errorhandling.exceptions.ResultSetVerificationException;
 
+/**
+ * Throws a {@link ResultSetVerificationException} unless there is exactly one row in the result set.
+ */
 public class AssertSingleRowResultSet implements ResultSetCycleOperator {
 
     @Override

activitytype-cql/src/main/java/io/nosqlbench/activitytype/cql/statements/rsoperators/CqlResultSetLogger.java

@@ -5,6 +5,10 @@ import io.nosqlbench.activitytype.cql.api.ResultSetCycleOperator;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 
+/**
+ * Logs a trace-level event for the result set, including
+ * cycles, rows, fetched row count, and the statement.
+ */
 public class CqlResultSetLogger implements ResultSetCycleOperator {
     private final static Logger logger = LoggerFactory.getLogger(CqlResultSetLogger.class);
 

activitytype-cql/src/main/java/io/nosqlbench/activitytype/cql/statements/rsoperators/PerThreadCQLData.java

@@ -4,6 +4,11 @@ import com.datastax.driver.core.Row;
 
 import java.util.LinkedList;
 
+/**
+ * This contains a linked list of {@link Row} objects. This is per-thread.
+ * You can use this list as a per-thread data cache for sharing data between
+ * cycles in the same thread.
+ */
 public class PerThreadCQLData {
     public final static ThreadLocal<LinkedList<Row>> rows = ThreadLocal.withInitial(LinkedList::new);
 }

engine-cli/src/main/resources/basic.md

@@ -10,7 +10,7 @@
 # To run a simple built-in workload run:
     ./nb  cql-iot
 
-# To get a list of available workloads run:
+# To get a list of workloads run:
     ./nb --list-workloads
 
 # Note: this will include built-in workloads, shipped with nb and workloads in your local directory.

engine-docs/src/main/resources/docs-for-nb/basics/activity_parameters.md

@@ -18,11 +18,13 @@ called _core parameters_. Only core activity parameters are documented
 here.
 
 :::info
-To see what activity parameters are valid for a given activity type, see
+To see what activity parameters are valid for a given activity type, see the documentation for that activity type with
-the documentation for that activity type with `nosqlbench help <activity
+`nb help <activity type>`.
-type>`.
 :::
 
+When starting out, you want to familiarize yourself with these parameters. The most important ones to learn about first
+are driver, cycles and threads.
+
 ## driver
 
 For historic reasons, you can also use `type`. They both mean the same
@@ -233,8 +235,8 @@ above. If you do not specify it when you initialize a cyclerate, then it
 defaults 1.1. The burst ratio is only valid as part of a rate limit and
 can not be specified by itself.
 
-_default_: `1.1`
+* _default_: `1.1`
-_dynamic_: yes
+* _dynamic_: yes
 
 The nosqlbench rate limiter provides a sliding scale between strict rate
 limiting and average rate limiting. The difference between them is
@@ -259,13 +261,12 @@ near-strict behavior while allowing clients to still track truer to rate
 limit expectations, so long as the overall workload is not saturating
 resources.
 
-:::info The default burst ratio of 1.1 makes testing results slightly
+:::info
-more stable on average, but can also hide some short-term slow-downs in
+The default burst ratio of 1.1 makes testing results slightly more stable on average, but can also hide some
-system throughput. It is set at the default to fit most tester's
+short-term slow-downs in system throughput. It is set at the default to fit most tester's expectations for averaging
-expectations for averaging results, but it may not be strict enough for
+results, but it may not be strict enough for your testing purposes. However, a strict setting of 1.0 nearly always adds
-your testing purposes. However, a strict setting of 1.0 nearly always
+cold/startup time to the result, so if you are testing for steady state, be sure to account for this across test runs.
-adds cold/startup time to the result, so if you are testing for steady
+:::
-state, be sure to account for this across test runs. :::
 
 ## striderate
 
@@ -289,11 +290,11 @@ to optimize a client runtime for more efficiency and throughput. The stride
 rate limiter applies to the whole activity irrespective of how many threads
 it has.
 
-:::warning When using the cyclerate an striderate options together,
+:::warning
-operations are delayed based on both rate limiters. If the relative
+When using the cyclerate an striderate options together, operations are delayed based on both rate limiters. If the
-rates are not synchronised with the side of a stride, then one rate
+relative rates are not synchronised with the side of a stride, then one rate limiter will artificially throttle the
-limiter will artificially throttle the other. Thus, it usually doesn't
+other. Thus, it usually doesn't make sense to use both of these settings in the same activity.
-make sense to use both of these settings in the same activity. :::
+:::
 
 ## seq
 

engine-docs/src/main/resources/docs-for-nb/builtins/index.md

@@ -1,36 +0,0 @@
----
-title: Built-In Workloads
-weight: 40
----
-
-# Built-In Workloads
-
-There are a few built-in workloads which you may want to run. These workloads can be run from a command without having
-to configure anything, or they can be tailored with their built-in parameters.
-
-There is now a way to list the built-in workloads:
-
-`nb --list-workloads` will give you a list of all the pre-defined workloads which have a named scenarios built-in.
-
-## Common Built-Ins
-
-This section of the guidebook will explain a couple of the common scenarios in detail.
-
-## Built-In Workload Conventions
-
-The built-in workloads follow a set of conventions so that they can be used interchangeably:
-
-### Phases
-
-Each built-in contains the following tags that can be used to break the workload up into uniform phases:
-
-- schema - selected with `tags=phase:schema`
-- rampup - selected with `tags=phase:rampup`
-- main - selected with `tags=phase:main`
-
-### Parameters
-
-Each built-in has a set of adjustable parameters which is documented below per workload. For example, the cql-iot
-workload has a `sources` parameter which determines the number of unique devices in the dataset.
-
-

engine-docs/src/main/resources/docs-for-nb/getting_started/index.md

@@ -31,19 +31,18 @@ the jar, just replace `./nb` with `java -jar nb.jar` when running commands.
 
 To run a simple built-in workload run:
 
-    ./nb  cql-iot
+    ./nb cql-iot
-
 
 To get a list of built-in workloads run:
 
     ./nb --list-workloads
 
 :::info
-Note:  this will include workloads that were shipped with nb and workloads in your local directory.
+Note: this will include workloads that were shipped with nb and workloads in your local directory. To learn more about
-To learn more about how to design custom workloads see [designing workloads](/index.html#/docs/04_designing_workloads.html)
+how to design custom workloads see
+[designing workloads](/index.html#/docs/designing_workloads.html)
 :::
 
-
 To provide your own contact points (comma separated), add the `hosts=` parameter
 
     ./nb  cql-iot hosts=host1,host2

engine-docs/src/main/resources/docs-for-nb/reference/parameter_types.md

@@ -29,7 +29,7 @@ activity type. Core activity params include type*, *alias*, and *threads*, for e
 individually under the next section.
 
 *Driver* Parameters are those provided by an activity type. These parameters are documented for each activity type. You
-can see them by running `nosqlbench help <activity type>`.
+can see them by running `nb help <activity type>`.
 
 Driver parameters may be dynamic. *Dynamic* Activity Parameters are parameters which may be changed while an activity is
 running. This means that scenario scripting logic may change some variables while an activity is running, and that the

engine-docs/src/main/resources/docs-for-nb/workloads/cql-iot.md

@@ -3,27 +3,15 @@ title: CQL IoT
 weight: 2
 ---
 
+# CQL IoT
+
 ## Description
 
 The CQL IoT workload demonstrates a time-series telemetry system as typically found in IoT applications. The bulk of the
 traffic is telemetry ingest. This is useful for establishing steady-state capacity with an actively managed data
 lifecycle. This is a steady-state workload, where inserts are 90% of the operations and queries are the remaining 10%.
 
-## Schema
+## Named Scenarios
-
-    CREATE KEYSPACE baselines WITH replication =
-        { 'class': 'NetworkTopologyStrategy', 'dc1': 3 };
-
-    CREATE TABLE baselines.iot (
-            station_id UUID,
-            machine_id UUID,
-            machine_type text,
-            sensor_value double,
-            time timestamp,
-            PRIMARY KEY (machine_id, time)
-        ) WITH CLUSTERING ORDER BY (time DESC)
-        AND compaction =  { 'class': 'TimeWindowCompactionStrategy' }
-        AND default_ttl = 3600;
 
 ## Workload Sequence
 

engine-docs/src/main/resources/docs-for-nb/workloads/cql-keyvalue.md

@@ -13,17 +13,6 @@ During preload, all keys are set with a value. During the main phase of the work
 population are replaced with new values which never repeat. During the main phase, random partitions are selected for
 upsert, with row values never repeating.
 
-## Schema
-
-    CREATE KEYSPACE baselines IF NOT EXISTS WITH replication =
-        { 'class': 'NetworkTopologyStrategy', 'dc1': 3 };
-
-    CREATE TABLE baselines.keyvalue (
-            user_id UUID,
-            user_code text
-            PRIMARY KEY (user_id)
-        );
-
 ## Workload Sequence
 
 1. schema - Initialize the schema.

engine-docs/src/main/resources/docs-for-nb/workloads/index.md

@@ -0,0 +1,63 @@
+---
+title: Built-In Workloads
+weight: 40
+---
+
+# Built-In Workloads
+
+There are a few built-in workloads which you may want to run. These can be run from a command without having to
+configure anything, or they can be tailored with their built-in parameters.
+
+## Finding Workloads
+
+To find the build-in scenarios, ask NoSQLBench like this:
+
+    nb --list-workloads
+
+This specifically lists the workloads which provide named scenarios. Only named scenarios are included. Workloads are
+contained in yaml files. If a yaml file is in the standard path and contains a root `scenarios` element, then it is
+included in the listing above.
+
+Each of these scenarios has a set of parameters which can be changed on the command line.
+
+## Running Workloads
+
+You can run them directly, by name with `nb <workload> [<scenario>] [<params>...]`. If not provided, scenario is assumed
+to be `default`.
+
+For example, the `cql-iot` workload is listed with the above command, and can be executed like this:
+
+    # put your normal extra params in ... below, like hosts, for example
+    nb cql-iot default ...
+
+    # OR, with scenario name default
+    nb cql-iot ...
+
+You can add any parameters to the end, and these parameters will be passed automatically to each stage of the scenario
+as needed. Within the scenario, designers have the ability to lock parameters so that overrides are used appropriately.
+
+## Conventions
+
+The built-in workloads follow a set of conventions so that they can be used interchangeably. This is more for users who
+are using the stages of these workloads directly, or for users who are designing new scenarios to be included in the
+built-ins.
+
+### Phases
+
+Each built-in contains the following tags that can be used to break the workload up into uniform phases:
+
+- schema - selected with `tags=phase:schema`
+- rampup - selected with `tags=phase:rampup`
+- main - selected with `tags=phase:main`
+
+### Parameters
+
+Each built-in has a set of adjustable parameters which is documented below per workload. For example, the cql-iot
+workload has a `sources` parameter which determines the number of unique devices in the dataset.
+
+## Adding Workloads
+
+If you want to add your own workload to NoSQLBench, or request a specific type of workload, please
+[Request a workload](https://github.com/nosqlbench/nosqlbench/issues) or
+[Submit a pull request](https://github.com/nosqlbench/nosqlbench/pulls).
+