update spectator-py docs for the 1.0 release (#179)

docs/spectator/lang/go/usage.md

@@ -96,14 +96,15 @@ func main() {
 
 ## Logging
 
-Logging is implemented with the standard Golang [slog package](https://pkg.go.dev/log/slog). The logger defines interfaces
-for [Debugf, Infof, and Errorf]. There are useful messages implemented at the Debug level which can
-help diagnose the metric publishing workflow. The logger can be overridden by providing one as the
-third parameter of the `Config` constructor.
+Logging is implemented with the standard Golang [slog package](https://pkg.go.dev/log/slog). The
+logger defines interfaces for [Debugf, Infof, and Errorf]. There are useful messages implemented at
+the Debug level which can help diagnose the metric publishing workflow. The logger can be overridden
+by providing one as the third parameter of the `Config` constructor.
 
 [Debugf, Infof, and Errorf]: https://github.com/Netflix/spectator-go/blob/main/spectator/logger/logger.go
 
 ## Runtime Metrics
 
-Use [spectator-go-runtime-metrics](https://github.com/Netflix/spectator-go-runtime-metrics). Follow instructions
-in the [README](https://github.com/Netflix/spectator-go-runtime-metrics) to enable collection.
+Use [spectator-go-runtime-metrics](https://github.com/Netflix/spectator-go-runtime-metrics). Follow
+instructions in the [README](https://github.com/Netflix/spectator-go-runtime-metrics) to enable
+collection.

docs/spectator/lang/py/meters/age-gauge.md

@@ -7,17 +7,25 @@ Time Since Last Success alerting pattern.
 To set a specific time as the last success:
 
 ```python
-from spectator import GlobalRegistry
+from spectator.registry import Registry
 
-GlobalRegistry.age_gauge("time.sinceLastSuccess").set(1611081000)
+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:
 
 ```python
-from spectator import GlobalRegistry
+from spectator.registry import Registry
+
+registry = Registry()
+registry.age_gauge("time.sinceLastSuccess").now()
 
-GlobalRegistry.age_gauge("time.sinceLastSuccess").set(0)
+last_success = registry.new_id("time.sinceLastSuccess")
+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
@@ -28,7 +36,7 @@ Since Age Gauges are long-lived entities that reside in the memory of the Specta
 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:
+**Example:**
 
 ```
 curl -X DELETE \

docs/spectator/lang/py/meters/counter.md

@@ -1,22 +1,30 @@
-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.
+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.
+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:
 
 ```python
-from spectator import GlobalRegistry
+from spectator.registry import Registry
 
-GlobalRegistry.counter("server.numRequests").increment()
+registry = Registry()
+registry.counter("server.numRequests").increment()
+
+num_requests = registry.new_id("server.numRequests")
+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:
 
 ```python
-from spectator import GlobalRegistry
+from spectator.registry import Registry
+
+registry = Registry()
+registry.counter("queue.itemsAdded").increment(10)
 
-GlobalRegistry.counter("queue.itemsAdded").increment(10)
+num_requests = registry.new_id("server.numRequests")
+registry.counter_with_id(num_requests).increment(10)
 ```

docs/spectator/lang/py/meters/dist-summary.md

@@ -9,7 +9,11 @@ This means that a `4K` tick label will represent 4 kilobytes, rather than 4 kilo
 Call `record()` with a value:
 
 ```python
-from spectator import GlobalRegistry
+from spectator.registry import Registry
 
-GlobalRegistry.distribution_summary("server.requestSize").record(10)
+registry = Registry()
+registry.distribution_summary("server.requestSize").record(10)
+
+request_size = registry.new_id("server.requestSize")
+registry.distribution_summary_with_id(request_size).record(10)
 ```

docs/spectator/lang/py/meters/gauge.md

@@ -9,17 +9,25 @@ higher or lower at some point during interval, but that is not known.
 Call `set()` with a value:
 
 ```python
-from spectator import GlobalRegistry
+from spectator.registry import Registry
 
-GlobalRegistry.gauge("server.queueSize").set(10)
+registry = Registry()
+registry.gauge("server.queueSize").set(10)
+
+queue_size = registry.new_id("server.queueSize")
+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.
 
 ```python
-from spectator import GlobalRegistry
+from spectator.registry import Registry
+
+registry = Registry()
+registry.gauge("server.queueSize", ttl_seconds=120).set(10)
 
-GlobalRegistry.gauge("server.queueSize", ttl_seconds=120).set(10)
+queue_size = registry.new_id("server.queueSize")
+registry.gauge_with_id(queue_size, ttl_seconds=120).set(10)
 ```

docs/spectator/lang/py/meters/max-gauge.md

@@ -6,7 +6,11 @@ standard Gauges, Max Gauges do not continue to report to the backend, and there
 Call `set()` with a value:
 
 ```python
-from spectator import GlobalRegistry
+from spectator.registry import Registry
 
-GlobalRegistry.max_gauge("server.queueSize").set(10)
+registry = Registry()
+registry.max_gauge("server.queueSize").set(10)
+
+queue_size = registry.new_id("server.queueSize")
+registry.max_gauge_with_id(queue_size).set(10)
 ```

docs/spectator/lang/py/meters/monotonic-counter-uint.md

@@ -0,0 +1,18 @@
+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:
+
+```python
+from ctypes import c_uint64
+from spectator.registry import Registry
+
+registry = Registry()
+registry.monotonic_counter_uint("iface.bytes").set(c_uint64(1))
+
+iface_bytes = registry.new_id("iface.bytes")
+registry.monotonic_counter_uint_with_id(iface_bytes).set(c_uint64(1))
+```

docs/spectator/lang/py/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:
+
+```python
+from spectator.registry import Registry
+
+registry = Registry()
+registry.monotonic_counter("iface.bytes").set(10)
+
+iface_bytes = registry.new_id("iface.bytes")
+registry.monotonic_counter_with_id(iface_bytes).set(10)
+```

docs/spectator/lang/py/meters/pct-dist-summary.md → docs/spectator/lang/py/meters/percentile-dist-summary.md

@@ -1,5 +1,5 @@
 The value tracks the distribution of events, with percentile estimates. It is similar to a
-Percentile Timer, but more general, because the size does not have to be a period of time.
+`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.
@@ -11,7 +11,11 @@ added to Percentile Distribution Summaries and ensure that they have a small bou
 Call `record()` with a value:
 
 ```python
-from spectator import GlobalRegistry
+from spectator.registry import Registry
 
-GlobalRegistry.pct_distribution_summary("server.requestSize").record(10)
+registry = Registry()
+registry.pct_distribution_summary("server.requestSize").record(10)
+
+request_size = registry.new_id("server.requestSize")
+registry.pct_distribution_summary_with_id(request_size).record(10)
 ```

docs/spectator/lang/py/meters/pct-timer.md → docs/spectator/lang/py/meters/percentile-timer.md

@@ -11,20 +11,28 @@ Timers and ensure that they have a small bounded cardinality.
 Call `record()` with a value:
 
 ```python
-from spectator import GlobalRegistry
+from spectator.registry import Registry
 
-GlobalRegistry.pct_timer("server.requestLatency").record(0.01)
+registry = Registry()
+registry.pct_timer("server.requestLatency").record(0.01)
+
+request_latency = registry.new_id("server.requestLatency")
+registry.pct_timer_with_id(request_latency).record(0.01)
 ```
 
-A `stopwatch()` method is available which may be used as a [Context Manager](https://docs.python.org/3/reference/datamodel.html#context-managers)
-to automatically record the number of seconds that have elapsed while executing a block of code:
+A `StopWatch` class is available, which may be used as a [Context Manager] to automatically record
+the number of seconds that have elapsed while executing a block of code:
 
 ```python
 import time
-from spectator import GlobalRegistry
+from spectator.registry import Registry
+from spectator.stopwatch import StopWatch
 
-t = GlobalRegistry.pct_timer("thread.sleep")
+registry = Registry()
+thread_sleep = registry.pct_timer("thread.sleep")
 
-with t.stopwatch():
+with StopWatch(thread_sleep):
     time.sleep(5)
 ```
+
+[Context Manager]: https://docs.python.org/3/reference/datamodel.html#context-managers

docs/spectator/lang/py/meters/timer.md

@@ -3,29 +3,28 @@ A Timer is used to measure how long (in seconds) some event is taking.
 Call `record()` with a value:
 
 ```python
-from spectator import GlobalRegistry
+from spectator.registry import Registry
 
-GlobalRegistry.timer("server.requestLatency").record(0.01)
+registry = Registry()
+registry.timer("server.requestLatency").record(0.01)
+
+request_latency = registry.new_id("server.requestLatency")
+registry.timer_with_id(request_latency).record(0.01)
 ```
 
-A `stopwatch()` method is available which may be used as a [Context Manager] to automatically record
+A `StopWatch` class is available, which may be used as a [Context Manager] to automatically record
 the number of seconds that have elapsed while executing a block of code:
 
 ```python
 import time
-from spectator import GlobalRegistry
+from spectator.registry import Registry
+from spectator.stopwatch import StopWatch
 
-t = GlobalRegistry.timer("thread.sleep")
+registry = Registry()
+thread_sleep = registry.timer("thread.sleep")
 
-with t.stopwatch():
+with StopWatch(thread_sleep):
     time.sleep(5)
 ```
 
-Internally, Timers will keep track of the following statistics as they are used:
-
-* `count`
-* `totalTime`
-* `totalOfSquares`
-* `max`
-
 [Context Manager]: https://docs.python.org/3/reference/datamodel.html#context-managers