update spectator-js docs for the thin-client release (#195)

Author: copperlight

Diff for: docs/spectator/lang/nodejs/meters/age-gauge.md

@@ -0,0 +1,51 @@
+The value is the time in seconds since the epoch at which an event has successfully occurred, or
+`0` to use the current time in epoch seconds. After an Age Gauge has been set, it will continue
+reporting the number of seconds since the last time recorded, for as long as the SpectatorD
+process runs. The purpose of this metric type is to enable users to more easily implement the
+Time Since Last Success alerting pattern.
+
+To set a specific time as the last success:
+
+```python
+from spectator import Registry
+
+registry = Registry()
+registry.age_gauge("time.sinceLastSuccess").set(1611081000)
+
+last_success = registry.new_id("time.sinceLastSuccess")
+registry.age_gauge_with_id(last_success).set(1611081000)
+```
+
+To set `now()` as the last success:
+
+```javascript
+import {Registry} from "nflx-spectator";
+
+const registry = new Registry();
+void registry.age_gauge("time.sinceLastSuccess").now();
+
+const last_success = registry.new_id("time.sinceLastSuccess");
+void registry.age_gauge_with_id(last_success).now();
+```
+
+By default, a maximum of `1000` Age Gauges are allowed per `spectatord` process, because there is no
+mechanism for cleaning them up. This value may be tuned with the `--age_gauge_limit` flag on the
+`spectatord` binary.
+
+Since Age Gauges are long-lived entities that reside in the memory of the SpectatorD process, if
+you need to delete and re-create them for any reason, then you can use the [SpectatorD admin server]
+to accomplish this task. You can delete all Age Gauges or a single Age Gauge.
+
+**Example:**
+
+```
+curl -X DELETE \
+http://localhost:1234/metrics/A
+```
+
+```
+curl -X DELETE \
+http://localhost:1234/metrics/A/fooIsTheName,some.tag=val1,some.otherTag=val2
+```
+
+[SpectatorD admin server]: ../../../agent/usage.md#admin-server

Diff for: docs/spectator/lang/nodejs/meters/counter.md

@@ -1 +1,30 @@
-TBD
+A Counter is used to measure the rate at which an event is occurring. Considering an API endpoint,
+a Counter could be used to measure the rate at which it is being accessed.
+
+Counters are reported to the backend as a rate-per-second. In Atlas, the `:per-step` operator can
+be used to convert them back into a value-per-step on a graph.
+
+Call `increment()` when an event occurs:
+
+```javascript
+import {Registry} from "nflx-spectator";
+
+const registry = new Registry();
+void registry.counter("server.numRequests").increment();
+
+const num_requests = registry.new_id("server.numRequests");
+void registry.counter_with_id(num_requests).increment();
+```
+
+You can also pass a value to `increment()`. This is useful when a collection of events happens
+together:
+
+```javascript
+import {Registry} from "nflx-spectator";
+
+const registry = new Registry();
+void registry.counter("queue.itemsAdded").increment(10);
+
+const num_requests = registry.new_id("server.numRequests");
+void registry.counter_with_id(num_requests).increment(10);
+```

Diff for: docs/spectator/lang/nodejs/meters/dist-summary.md

@@ -1 +1,19 @@
-TBD
+A Distribution Summary is used to track the distribution of events. It is similar to a Timer, but
+more general, in that the size does not have to be a period of time. For example, a Distribution
+Summary could be used to measure the payload sizes of requests hitting a server.
+
+Always use base units when recording data, to ensure that the tick labels presented on Atlas graphs
+are readable. If you are measuring payload size, then use bytes, not kilobytes (or some other unit).
+This means that a `4K` tick label will represent 4 kilobytes, rather than 4 kilo-kilobytes.
+
+Call `record()` with a value:
+
+```javascript
+import {Registry} from "nflx-spectator";
+
+const registry = new Registry();
+void registry.distribution_summary("server.requestSize").record(10);
+
+const request_size = registry.new_id("server.requestSize");
+void registry.distribution_summary_with_id(request_size).record(10);
+```

Diff for: docs/spectator/lang/nodejs/meters/gauge.md

@@ -1 +1,33 @@
-TBD
+A gauge is a value that is sampled at some point in time. Typical examples for gauges would be
+the size of a queue or number of threads in a running state. Since gauges are not updated inline
+when a state change occurs, there is no information about what might have occurred between samples.
+
+Consider monitoring the behavior of a queue of tasks. If the data is being collected once a minute,
+then a gauge for the size will show the size when it was sampled. The size may have been much
+higher or lower at some point during interval, but that is not known.
+
+Call `set()` with a value:
+
+```javascript
+import {Registry} from "nflx-spectator";
+
+const registry = new Registry();
+void registry.gauge("server.queueSize").set(10);
+
+const queue_size = registry.new_id("server.queueSize");
+void registry.gauge_with_id(queue_size).set(10);
+```
+
+Gauges will report the last set value for 15 minutes. This done so that updates to the values do
+not need to be collected on a tight 1-minute schedule to ensure that Atlas shows unbroken lines in
+graphs. A custom TTL may be configured for gauges. SpectatorD enforces a minimum TTL of 5 seconds.
+
+```javascript
+import {Registry} from "nflx-spectator";
+
+const registry = new Registry();
+void registry.gauge("server.queueSize", ttl_seconds=120).set(10);
+
+const queue_size = registry.new_id("server.queueSize");
+void registry.gauge_with_id(queue_size, ttl_seconds=120).set(10);
+```

Diff for: docs/spectator/lang/nodejs/meters/max-gauge.md

@@ -0,0 +1,16 @@
+The value is a number that is sampled at a point in time, but it is reported as a maximum Gauge
+value to the backend. This ensures that only the maximum value observed during a reporting interval
+is sent to the backend, thus over-riding the last-write-wins semantics of standard Gauges. Unlike
+standard Gauges, Max Gauges do not continue to report to the backend, and there is no TTL.
+
+Call `set()` with a value:
+
+```javascript
+import {Registry} from "nflx-spectator";
+
+const registry = new Registry();
+void registry.max_gauge("server.queueSize").set(10);
+
+const queue_size = registry.new_id("server.queueSize");
+void registry.max_gauge_with_id(queue_size).set(10);
+```

Diff for: docs/spectator/lang/nodejs/meters/monotonic-counter-uint.md

@@ -0,0 +1,17 @@
+A Monotonic Counter (uint64) is used to measure the rate at which an event is occurring, when the
+source data is a monotonically increasing number. A minimum of two samples must be sent, in order to
+calculate a delta value and report it to the backend as a rate-per-second. A variety of networking
+metrics may be reported monotonically, and this metric type provides a convenient means of recording
+these values, at the expense of a slower time-to-first metric.
+
+Call `set()` when an event occurs:
+
+```javascript
+import {Registry} from "nflx-spectator";
+
+const registry = new Registry();
+void registry.monotonic_counter_uint("iface.bytes").set(BigInt(1));
+
+const iface_bytes = registry.new_id("iface.bytes");
+void registry.monotonic_counter_uint_with_id(iface_bytes).set(BigInt(1));
+```

Diff for: docs/spectator/lang/nodejs/meters/monotonic-counter.md

@@ -0,0 +1,17 @@
+A Monotonic Counter (float) is used to measure the rate at which an event is occurring, when the
+source data is a monotonically increasing number. A minimum of two samples must be sent, in order to
+calculate a delta value and report it to the backend as a rate-per-second. A variety of networking
+metrics may be reported monotonically, and this metric type provides a convenient means of recording
+these values, at the expense of a slower time-to-first metric.
+
+Call `set()` when an event occurs:
+
+```javascript
+import {Registry} from "nflx-spectator";
+
+const registry = new Registry();
+void registry.monotonic_counter("iface.bytes").set(10);
+
+const iface_bytes = registry.new_id("iface.bytes");
+void registry.monotonic_counter_with_id(iface_bytes).set(10)
+```

Diff for: docs/spectator/lang/nodejs/meters/percentile-dist-summary.md

@@ -0,0 +1,21 @@
+The value tracks the distribution of events, with percentile estimates. It is similar to a
+`PercentileTimer`, but more general, because the size does not have to be a period of time.
+
+For example, it can be used to measure the payload sizes of requests hitting a server or the
+number of records returned from a query.
+
+In order to maintain the data distribution, they have a higher storage cost, with a worst-case of
+up to 300X that of a standard Distribution Summary. Be diligent about any additional dimensions
+added to Percentile Distribution Summaries and ensure that they have a small bounded cardinality.
+
+Call `record()` with a value:
+
+```javascript
+import {Registry} from "nflx-spectator";
+
+const registry = new Registry();
+void registry.pct_distribution_summary("server.requestSize").record(10);
+
+const request_size = registry.new_id("server.requestSize");
+void registry.pct_distribution_summary_with_id(request_size).record(10);
+```

Diff for: docs/spectator/lang/nodejs/meters/percentile-timer.md

@@ -1 +1,28 @@
-TBD
+The value is the number of seconds that have elapsed for an event, with percentile estimates.
+
+This metric type will track the data distribution by maintaining a set of Counters. The
+distribution can then be used on the server side to estimate percentiles, while still
+allowing for arbitrary slicing and dicing based on dimensions.
+
+In order to maintain the data distribution, they have a higher storage cost, with a worst-case of
+up to 300X that of a standard Timer. Be diligent about any additional dimensions added to Percentile
+Timers and ensure that they have a small bounded cardinality.
+
+Call `record()` with a value:
+
+```javascript
+import {Registry} from "nflx-spectator";
+
+const registry = new Registry();
+void registry.pct_timer("server.requestLatency").record(0.01);
+
+const request_latency = registry.new_id("server.requestLatency");
+void registry.pct_timer_with_id(request_latency).record(0.01);
+
+const start = process.hrtime();
+// do work
+void registry.pct_timer("server.requestLatency").record(process.hrtime(start));
+```
+
+The `record()` method accepts `number[]` output from `hrtime` and converts it to seconds, as a
+convenience for recording latencies.

Diff for: docs/spectator/lang/nodejs/meters/timer.md

@@ -1 +1,20 @@
-TBD
+A Timer is used to measure how long (in seconds) some event is taking.
+
+Call `record()` with a value:
+
+```javascript
+import {Registry} from "nflx-spectator";
+
+const registry = new Registry();
+void registry.timer("server.requestLatency").record(0.01);
+
+const request_latency = registry.new_id("server.requestLatency");
+void registry.timer_with_id(request_latency).record(0.01);
+
+const start = process.hrtime();
+// do work
+void registry.timer("server.requestLatency").record(process.hrtime(start));
+```
+
+The `record()` method accepts `number[]` output from `hrtime` and converts it to seconds, as a
+convenience for recording latencies.

Diff for: docs/spectator/lang/nodejs/migrations.md

@@ -0,0 +1 @@
+TBD