[5pt] Improve the metrics doc

[patiencedaur]

Improve the metrics documentation

Follow-up on tarantool/metrics#310.

Product: metrics
Audience/target: dev
Root document: https://tarantool.io/en/doc/latest/book/monitoring/
SME: @ yngvar-antonsson

Details

For more info about collectors, check the Prometheus documentation---they are very similar.

The documentation on the metrics module is quite entangled now. Here are some ideas:

• Add introductory text describing each chapter's contents
• API: Move the description of the observation object to a more appropriate place (top?)
• API: consider defining summary-specific concepts in a separate section. Currently the description of summary object parameters looks way overloaded. Maybe connect them with the 'observation' object description. As for quantiles, consider creating a special .. note::. See the Prometheus doc for ideas how to organize this
• API: take out the description of label_pairs from function parameters to a separate place. This way the reader doesn't have to figure it out from context or learn about it post factum
• API: explain the difference between collectors
• API: if histogram and summary are "sets" of collectors (as defined in the note sections), why list them among the collectors?
• Distinguish between the list of collector names provided in the API chapter and the list provided in the "metrics reference". This might involve some refactoring
• Use similar syntax and formatting for similar sentences. For example, use the imperative mood for all function definitions ("Remove ...", not "Removes ...")
• Bring the API doc in accordance with our style guide. For example, always specify return values and types; consider adding the "Possible errors" section to the functions; make function descriptions overall consistent.

[andreyaksenov]

Metrics docs were improved when updating them to using Tarantool 3.x: #4348