Make more explicit that recording a metric is safe to call

[cbrachem]

I've added a TIP block to the Registry's docs to make it more explicit what happens when operations on Meters like incrementCount are called, which will make it clear that such operations are safe to call from regular code.

This PR is the result of a discussion in Slack.

Of course, feel free to challenge the general usefulness of the added paragraph, its accuracy and wording.

[shakuzen]

Thank you for the pull request. This is useful info to add to the docs for sure. I left some review.

[shakuzen]

I would simplify the first part to something along the lines "recording a measurement for a Meter is expected to be a relatively cheap operation and it should not throw any exception."
The second sentence is about publishing which is a bit implementation dependent. Perhaps I would word it as something like "if the registry supports publishing metrics to a metrics backend, this should be done on a separate thread from recording metrics"

There's also a bit of a question of whether both these belong in this page (Registry) of the docs. Maybe we should move the Meters page to before the Registry page in the table of contents and have the first part about recording measurements there?

[cbrachem]

I would simplify the first part to something along the lines "recording a measurement for a Meter is expected to be a relatively cheap operation and it should not throw any exception."
The second sentence is about publishing which is a bit implementation dependent. Perhaps I would word it as something like "if the registry supports publishing metrics to a metrics backend, this should be done on a separate thread from recording metrics"

Sounds good, I will rephrase according to your suggestion.

There's also a bit of a question of whether both these belong in this page (Registry) of the docs. Maybe we should move the Meters page to before the Registry page in the table of contents and have the first part about recording measurements there?

Interesting. That might be nice. Let me try and move things around a bit and then we can see how it looks.

[cbrachem]

@shakuzen Is this what you had in mind?

[shakuzen]

Yes, that looks good to me. I left a minor review comment.

[shakuzen]

Thank you for the documentation improvement.

[shakuzen]

I've rebased the pull request on the 1.12.x branch so we can add apply this change which is applicable to the oldest version of the docs maintained here and merge forward.