Review feedback

- Clarify language around mock `nexus`
- Add example to `how-to-run.adoc`

docs/how-to-run.adoc

@@ -697,3 +697,37 @@ To build a recovery host image:
 ----
 $ ./tools/build-host-image.sh -R $HELIOS_PATH /work/trampoline-global-zone-packages.tar.gz
 ----
+
+
+== Running `oximeter` in standalone mode
+
+`oximeter` is the program used to collect metrics from producers in the control
+plane. Normally, the producers register themselves with `nexus`, which creates a
+durable assignment between the producer and an `oximeter` collector in the
+database. That allows components to survive restarts, while still producing
+metrics.
+
+To ease development, `oximeter` can be run in "standalone" mode. In this case, a
+mock `nexus` server is started, with only the minimal subset of the internal API
+needed to register producers and collectors. Neither CockroachDB nor ClickHouse
+is required, although ClickHouse _can_ be used, if one wants to see how data is
+inserted into the database.
+
+To run `oximeter` in standalone, use:
+
+[source,console]
+----
+$ cargo run --bin oximeter -- standalone
+----
+
+The producer should still register with `nexus` as normal, which is usually done
+with an explicit IP address and port. This defaults to `[::1]:12221`.
+
+When run this way, `oximeter` will print the samples it collects from the
+producers to its logs, like so:
+
+[source,console]
+----
+Sep 26 17:48:56.006 INFO sample: Sample { measurement: Measurement { timestamp: 2023-09-26T17:48:56.004565890Z, datum: CumulativeF64(Cumulative { start_time: 2023-09-26T17:48:45.997404777Z, value: 10.007154703 }) }, timeseries_name: "virtual_machine:cpu_busy", target: FieldSet { name: "virtual_machine", fields: {"instance_id": Field { name: "instance_id", value: Uuid(564ef6df-d5f6-4204-88f7-5c615859cfa7) }, "project_id": Field { name: "project_id", value: Uuid(2dc7e1c9-f8ac-49d7-8292-46e9e2b1a61d) }} }, metric: FieldSet { name: "cpu_busy", fields: {"cpu_id": Field { name: "cpu_id", value: I64(0) }} } }, component: results-sink, collector_id: 78c7c9a5-1569-460a-8899-aada9ad5db6c, component: oximeter-standalone, component: nexus-standalone, file: oximeter/collector/src/lib.rs:280
+Sep 26 17:48:56.006 INFO sample: Sample { measurement: Measurement { timestamp: 2023-09-26T17:48:56.004700841Z, datum: CumulativeF64(Cumulative { start_time: 2023-09-26T17:48:45.997405187Z, value: 10.007154703 }) }, timeseries_name: "virtual_machine:cpu_busy", target: FieldSet { name: "virtual_machine", fields: {"instance_id": Field { name: "instance_id", value: Uuid(564ef6df-d5f6-4204-88f7-5c615859cfa7) }, "project_id": Field { name: "project_id", value: Uuid(2dc7e1c9-f8ac-49d7-8292-46e9e2b1a61d) }} }, metric: FieldSet { name: "cpu_busy", fields: {"cpu_id": Field { name: "cpu_id", value: I64(1) }} } }, component: results-sink, collector_id: 78c7c9a5-1569-460a-8899-aada9ad5db6c, component: oximeter-standalone, component: nexus-standalone, file: oximeter/collector/src/lib.rs:280
+----

oximeter/collector/src/bin/oximeter.rs

@@ -68,10 +68,10 @@ enum Args {
     ///
     /// In this mode, `oximeter` can be used to test the collection of metrics
     /// from producers, without requiring all the normal machinery of the
-    /// control plane. The collector is run as usual, but additionally starts an
+    /// control plane. The collector is run as usual, but additionally starts a
     /// API server to stand-in for Nexus. The registrations of the producers and
-    /// collectors occurs through the normal code path, but uses this standalone
-    /// Nexus instead of the real thing.
+    /// collectors occurs through the normal code path, but uses this mock Nexus
+    /// instead of the real thing.
     Standalone {
         /// The ID for the collector.
         ///
@@ -89,9 +89,9 @@ enum Args {
         )]
         address: SocketAddrV6,
 
-        /// The address for the fake Nexus server used to register.
+        /// The address for the mock Nexus server used to register.
         ///
-        /// This program starts a fake version of Nexus, which is used only to
+        /// This program starts a mock version of Nexus, which is used only to
         /// register the producers and collectors. This allows them to operate
         /// as they usually would, registering each other with Nexus so that an
         /// assignment between them can be made.