improve java timers documentation (#228)

There is still a bit of confusion about the fact that Java Timers always report
values in seconds. This is an attempt to provide a more complete explanation
that Java Timers do this, with references to how it is implemented in code.

Author: copperlight

docs/concepts/naming.md

@@ -95,7 +95,21 @@ further filter the data to a subset in which you have an interest.
 
 ## Use Base Units
 
-Keep measurements in base units where possible. It is better to have all timers in seconds, disk
-sizes in bytes, and network rates in bytes/second. This allows any SI unit prefixes applied to
-tick labels on a graph to have an obvious meaning, such as 1k meaning 1 kilobyte, as opposed to
-1 kilo-megabyte.
+**Keep measurements in base units, whenever and wherever possible.**
+
+It is best to have timers in `seconds`, disk sizes in `bytes`, and network rates in `bytes/second`.
+This allows any International System of Units (SI) prefixes applied to [tick labels] on a graph to
+have an obvious meaning, such as:
+
+* `1 m` meaning `1 millisecond`, as opposed to `1 milli-millisecond`, for timers.
+* `1 k` meaning `1 kilobyte`, as opposed to `1 kilo-megabyte`, for disk sizes.
+* `1 M` meaning `1 megabyte/second`, as opposed to `1 mega-kilobyte`, for network rates.
+
+Atlas automatically applies tick labels to the Y-axis of the graph, in order to accurately report
+the magnitude of values, while keeping them within the view window.
+
+Some meters in some clients, such as [Java Timers], will automatically constrain values to base
+units in their implementations.
+
+[tick labels]: ../api/graph/tick.md
+[Java Timers]: ../spectator/lang/java/meters/timer.md#units

docs/spectator/lang/cpp/meters/percentile-timer.md

@@ -1,3 +1,5 @@
+## Percentile Timer
+
 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
@@ -27,3 +29,7 @@ int main()
     r.CreatePercentTimer(requestLatencyMeter).Record(10);
 }
 ```
+
+## Units
+
+See [Timer Units](timer.md#units) for an explanation.

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

@@ -1,3 +1,5 @@
+## Timer
+
 A Timer is used to measure how long (in seconds) some event is taking.
 
 Call `Record()` with a value:
@@ -19,3 +21,10 @@ int main()
     r.CreateTimer(requestLatencyMeter).Record(10);
 }
 ```
+
+## Units
+
+Ensure that you always report values in seconds (see [Use Base Units]). The API does not offer any
+guarantees that the value will be in seconds.
+
+[Use Base Units]: ../../../../concepts/naming.md#use-base-units

docs/spectator/lang/go/meters/percentile-timer.md

@@ -1,3 +1,5 @@
+## Percentile Timer
+
 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
@@ -26,3 +28,7 @@ func main() {
 	registry.PercentileTimerWithId(requestLatency).Record(500 * time.Millisecond)
 }
 ```
+
+## Units
+
+See [Timer Units](timer.md#units) for an explanation.

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

@@ -1,3 +1,5 @@
+## Timer
+
 A Timer is used to measure how long (in seconds) some event is taking.
 
 Call `record()` with a value:
@@ -18,3 +20,11 @@ func main() {
 	registry.TimerWithId(requestLatency).Record(500 * time.Millisecond)
 }
 ```
+
+## Units
+
+Go Timers always report values to backends in seconds (see [Use Base Units]). The API accepts a
+[time.Duration] value, which is converted to seconds when reporting.
+
+[Use Base Units]: ../../../../concepts/naming.md#use-base-units
+[time.Duration]: https://pkg.go.dev/time#Duration

docs/spectator/lang/java/meters/percentile-timer.md

@@ -49,3 +49,6 @@ is recommended to use a monotonically increasing source for measuring the times,
 occasionally having bogus measurements due to time adjustments. For more information, see the
 [Clock documentation](../../../core/clock.md).
 
+## Units
+
+See [Timer Units](timer.md#units) for an explanation.

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

@@ -92,3 +92,15 @@ e.g., update a different Timer, if an exception is thrown.
 * Being a Gauge, it is inappropriate for short tasks. In particular, Gauges are sampled and if it
 is not sampled during the execution, or the sampling period is a significant subset of the expected
 duration, then the duration value will not be meaningful.
+
+## Units
+
+Java Timers always report values to backends in seconds (see [Use Base Units]). The API allows
+for recording elapsed time in different units, so it can easily be used with the common ways of
+measuring elapsed time provided by the SDK, such as [System.nanoTime()] (monotonic time) and
+[System.currentTimeMillis()] (wall clock). Regardless of how it is recorded, when queried on the
+backend, the unit will be seconds.
+
+[Use Base Units]: ../../../../concepts/naming.md#use-base-units
+[System.nanoTime()]: https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/lang/System.html#nanoTime()
+[System.currentTimeMillis()]: https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/lang/System.html#currentTimeMillis()

docs/spectator/lang/nodejs/meters/percentile-timer.md

@@ -1,3 +1,5 @@
+## Percentile Timer
+
 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
@@ -26,3 +28,7 @@ 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.
+
+## Units
+
+See [Timer Units](timer.md#units) for an explanation.

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

@@ -1,3 +1,5 @@
+## Timer
+
 A Timer is used to measure how long (in seconds) some event is taking.
 
 Call `record()` with a value:
@@ -18,3 +20,15 @@ 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.
+
+## Units
+
+If you use [process.hrtime()] or [process.hrtime.bigint()] to calculate the elapsed time, then the
+units will be converted to seconds when reporting values.
+
+If you use a plain `number` value to record values, then ensure that you always report values in
+seconds (see [Use Base Units]). No conversion assistance is provided in this case.
+
+[process.hrtime()]: https://nodejs.org/api/process.html#processhrtimetime
+[process.hrtime.bigint()]: https://nodejs.org/api/process.html#processhrtimebigint
+[Use Base Units]: ../../../../concepts/naming.md#use-base-units

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

@@ -1,3 +1,5 @@
+## Percentile Timer
+
 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
@@ -35,3 +37,7 @@ with StopWatch(thread_sleep):
 ```
 
 [Context Manager]: https://docs.python.org/3/reference/datamodel.html#context-managers
+
+## Units
+
+See [Timer Units](timer.md#units) for an explanation.