Skip to content

Commit

Permalink
Make clear need to maintain gauge object reference
Browse files Browse the repository at this point in the history
Previously the example code could be misinterpreted as being usable as-is in arbitrary places in code.
This commit adds comments to the example code to clarify the need to maintain a reference to the object backing the Gauge.
It also attempts to make clear the updating of the backing object can happen in arbitrary places, using the reference to the backing object.

Resolves #107
  • Loading branch information
shakuzen committed Dec 9, 2019
1 parent 70e0f05 commit f566862
Showing 1 changed file with 6 additions and 3 deletions.
9 changes: 6 additions & 3 deletions src/docs/concepts/gauges.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -27,9 +27,12 @@ A gauge can be made to track any `java.lang.Number` subtype that is settable, su

[source,java]
----
AtomicInteger n = registry.gauge("numberGauge", new AtomicInteger(0));
n.set(1);
n.set(2);
// maintain a reference to myGauge
AtomicInteger myGauge = registry.gauge("numberGauge", new AtomicInteger(0));
// ... elsewhere you can update the value it holds using the object reference
myGauge.set(27);
myGauge.set(11);
----

Note that in this form unlike other meter types you don't get a reference to the `Gauge` when creating one, but rather the thing being observed. This is because of the heisen-gauge principal; the gauge is self sufficient once created, so you should never need to interact with it. This allows us to give you back only the instrumented object, which allows for quick one liners that both create the object to be observed and set up metrics around it.
Expand Down

0 comments on commit f566862

Please sign in to comment.