add spectator-js migration docs and fill out spectator-go docs

Author: copperlight

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

@@ -0,0 +1,63 @@
+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:
+
+```golang
+import (
+	"github.com/Netflix/spectator-go/v2/spectator"
+)
+
+func main() {
+	config, _ := spectator.NewConfig("udp", nil, nil)
+	registry, _ := spectator.NewRegistry(config)
+
+	registry.AgeGauge("time.sinceLastSuccess", nil).Set(1611081000)
+
+	lastSuccess := registry.NewId("time.sinceLastSuccess", nil)
+	registry.AgeGaugeWithId(lastSuccess).set(1611081000)
+}
+```
+
+To set `Now()` as the last success:
+
+```golang
+import (
+	"github.com/Netflix/spectator-go/v2/spectator"
+)
+
+func main() {
+	config, _ := spectator.NewConfig("udp", nil, nil)
+	registry, _ := spectator.NewRegistry(config)
+
+	registry.AgeGauge("time.sinceLastSuccess", nil).Now()
+
+	lastSuccess := registry.NewId("time.sinceLastSuccess", nil)
+	registry.AgeGaugeWithId(lastSuccess).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/go/meters/counter.md

@@ -0,0 +1,42 @@
+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:
+
+```golang
+import (
+	"github.com/Netflix/spectator-go/v2/spectator"
+)
+
+func main() {
+	config, _ := spectator.NewConfig("udp", nil, nil)
+	registry, _ := spectator.NewRegistry(config)
+
+	registry.Counter("server.numRequests", nil).Increment()
+
+	numRequests := registry.NewId("server.numRequests", nil)
+	registry.CounterWithId(numRequests).Increment()
+}
+```
+
+You can also pass a value to `Add(int64)`, or `AddFloat(float64)`. This is useful when a collection
+of events happens together:
+
+```golang
+import (
+	"github.com/Netflix/spectator-go/v2/spectator"
+)
+
+func main() {
+	config, _ := spectator.NewConfig("udp", nil, nil)
+	registry, _ := spectator.NewRegistry(config)
+
+	registry.Counter("queue.itemsAdded", nil).Add(10)
+
+	numRequests := registry.NewId("server.numRequests", nil)
+	registry.CounterWithId(numRequests).Add(10)
+}
+```

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

@@ -0,0 +1,25 @@
+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:
+
+```golang
+import (
+	"github.com/Netflix/spectator-go/v2/spectator"
+)
+
+func main() {
+	config, _ := spectator.NewConfig("udp", nil, nil)
+	registry, _ := spectator.NewRegistry(config)
+
+	registry.DistributionSummary("server.requestSize", nil).Record(10)
+
+	requestSize := registry.NewId("server.requestSize", nil)
+	registry.DistributionSummaryWothId(requestSize).Record(10)
+}
+```

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

@@ -0,0 +1,46 @@
+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:
+
+```golang
+import (
+	"github.com/Netflix/spectator-go/v2/spectator"
+)
+
+func main() {
+	config, _ := spectator.NewConfig("udp", nil, nil)
+	registry, _ := spectator.NewRegistry(config)
+
+	registry.Gauge("server.queueSize", nil).Set(10)
+
+	queueSize := registry.NewId("server.queueSize", nil)
+	registry.GaugeWithId(queueSize).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.
+
+```golang
+import (
+	"github.com/Netflix/spectator-go/v2/spectator"
+	"time"
+)
+
+func main() {
+	config, _ := spectator.NewConfig("udp", nil, nil)
+	registry, _ := spectator.NewRegistry(config)
+
+	registry.GaugeWithTTL("server.queueSize", nil, 120 * time.Second).Set(10)
+
+	queueSize := registry.NewId("server.queueSize", nil)
+	registry.GaugeWithIdWithTTL(queueSize, 120 * time.Second).Set(10)
+}
+```

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

@@ -0,0 +1,22 @@
+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:
+
+```golang
+import (
+	"github.com/Netflix/spectator-go/v2/spectator"
+)
+
+func main() {
+	config, _ := spectator.NewConfig("udp", nil, nil)
+	registry, _ := spectator.NewRegistry(config)
+
+	registry.MaxGauge("server.queueSize", nil).Set(10)
+
+	queueSize := registry.NewId("server.queueSize", nil)
+	registry.MaxGaugeWithId(queueSize).Set(10)
+}
+```

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

@@ -0,0 +1,23 @@
+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:
+
+```golang
+import (
+	"github.com/Netflix/spectator-go/v2/spectator"
+)
+
+func main() {
+	config, _ := spectator.NewConfig("udp", nil, nil)
+	registry, _ := spectator.NewRegistry(config)
+
+	registry.MonotonicCounterUint("iface.bytes", nil).Set(1)
+
+	ifaceBytes := registry.NewId("iface.bytes", nil)
+	registry.MonotonicCounterUintWithId(ifaceBytes).Set(1)
+}
+```

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

@@ -0,0 +1,23 @@
+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:
+
+```golang
+import (
+	"github.com/Netflix/spectator-go/v2/spectator"
+)
+
+func main() {
+	config, _ := spectator.NewConfig("udp", nil, nil)
+	registry, _ := spectator.NewRegistry(config)
+
+	registry.MonotonicCounter("iface.bytes", nil).Set(10)
+
+	ifaceBytes := registry.NewId("iface.bytes", nil)
+	registry.MonotonicCounterWithId(ifaceBytes).Set(10)
+}
+```

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

@@ -0,0 +1,27 @@
+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:
+
+```golang
+import (
+	"github.com/Netflix/spectator-go/v2/spectator"
+)
+
+func main() {
+	config, _ := spectator.NewConfig("udp", nil, nil)
+	registry, _ := spectator.NewRegistry(config)
+
+	registry.PercentileDistributionSummary("server.requestSize", nil).Record(10)
+
+	requestSize := registry.NewId("server.requestSize", nil)
+	registry.PercentileDistributionSummaryWothId(requestSize).Record(10)
+}
+```

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

@@ -0,0 +1,28 @@
+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:
+
+```golang
+import (
+	"github.com/Netflix/spectator-go/v2/spectator"
+	"time"
+)
+
+func main() {
+	config, _ := spectator.NewConfig("udp", nil, nil)
+	registry, _ := spectator.NewRegistry(config)
+
+	registry.PercentileTimer("server.requestLatency", nil).Record(500 * time.Millisecond)
+
+	requestLatency := registry.NewId("server.requestLatency", nil)
+	registry.PercentileTimerWithId(requestLatency).Record(500 * time.Millisecond)
+}
+```

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

@@ -0,0 +1,20 @@
+A Timer is used to measure how long (in seconds) some event is taking.
+
+Call `record()` with a value:
+
+```golang
+import (
+	"github.com/Netflix/spectator-go/v2/spectator"
+	"time"
+)
+
+func main() {
+	config, _ := spectator.NewConfig("udp", nil, nil)
+	registry, _ := spectator.NewRegistry(config)
+
+	registry.Timer("server.requestLatency", nil).Record(500 * time.Millisecond)
+
+	requestLatency := registry.NewId("server.requestLatency", nil)
+	registry.TimerWithId(requestLatency).Record(500 * time.Millisecond)
+}
+```