Skip to content

Commit

Permalink
Merge cc08eec into eb35baf
Browse files Browse the repository at this point in the history
  • Loading branch information
@DifferentialOrange
DifferentialOrange authored Feb 16, 2023
2 parents eb35baf + cc08eec commit 3740bba
Show file tree
Hide file tree
Showing 21 changed files with 1,037 additions and 126 deletions.
9 changes: 9 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- values and effect (like default metrics callbacks) are preserved
between reloads;
- does not deal with external features like cartridge HTTP setup
- name prefixes for collectors
- exhaustive output for export and aggregating with `extended_format` option:
- `shared_collector_obj:collect()`;
- `counter_obj:collect()`;
- `gauge_obj:collect()`;
- `histogram_obj:collect()`;
- `summary_obj:collect()`;
- `metrics.collect()`;

### Changed
- Setup cartridge hotreload inside the role
Expand All @@ -26,6 +34,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
- Passing nonexistent metrics to `enable_default_metrics()`
- Using `{}` as `include` in `enable_default_metrics()`
to enable all metrics
- Control characters in collector kind, name, observation and global labels

## [0.16.0] - 2023-01-27
### Added
Expand Down
179 changes: 162 additions & 17 deletions doc/monitoring/api_reference.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -51,19 +51,55 @@ counter

.. _metrics-api_reference-counter_collect:

.. method:: collect()
.. method:: collect(opts)

:return: Array of ``observation`` objects for a given counter.
:param table opts: table of collect options:

* ``extended_format`` -- use extended format in the output.

:return: Array of ``observation`` objects for a given counter (by default or if
``extended format`` is ``false``). Otherwise returns a map with collector
description and structured observations.

.. code-block:: lua
counter_obj:collect{extended_format = false}
{
-- an observation
{
label_pairs: table, -- `label_pairs` key-value table
timestamp: ctype<uint64_t>, -- observation time (in microseconds)
value: number, -- current value
metric_name: string, -- metric name
},
-- another observation...
}
.. code-block:: lua
counter_obj:collect{extended_format = true}
{
label_pairs: table, -- `label_pairs` key-value table
timestamp: ctype<uint64_t>, -- current system time (in microseconds)
value: number, -- current value
metric_name: string, -- collector
name: string, -- collector name
name_prefix: string, -- collector name prefix
kind: string, -- collector kind
help: string, -- collector help
metainfo: table, -- collector metainfo
timestamp: ctype<uint64_t>, -- observation time (in microseconds)
observations = {
[''] = { -- map of observations
-- an observation
key: string = {
label_pairs: table, -- `label_pairs` key-value table
value: number, -- current value
},
-- another observation...
}
}
}
:rtype: table

.. _metrics-api_reference-counter_remove:
Expand Down Expand Up @@ -113,10 +149,15 @@ gauge

Sets the observation for ``label_pairs`` to ``num``.

.. method:: collect()
.. _metrics-api_reference-gauge_collect:

.. method:: collect(opts)

:param table opts: table of collect options:

Returns an array of ``observation`` objects for a given gauge.
For the description of ``observation``, see
* ``extended_format`` -- use extended format in the output.

Returns format is the same as for
:ref:`counter_obj:collect() <metrics-api_reference-counter_collect>`.

.. method:: remove(label_pairs)
Expand Down Expand Up @@ -170,11 +211,59 @@ histogram
Note that both label names and values in ``label_pairs``
are treated as strings.

.. method:: collect()
.. _metrics-api_reference-histogram_collect:

.. method:: collect(opts)

:param table opts: table of collect options:

Return a concatenation of ``counter_obj:collect()`` across all internal
counters of ``histogram_obj``. For the description of ``observation``,
see :ref:`counter_obj:collect() <metrics-api_reference-counter_collect>`.
* ``extended_format`` -- use extended format in the output.

:return: A concatenation of ``observation`` objects for a given counter (by default or if
``extended format`` is ``false``). Otherwise returns a map with collector
description and structured observations.

.. code-block:: lua
histogram_obj:collect{extended_format = false}
{
-- an observation
{
label_pairs: table, -- `label_pairs` key-value table
timestamp: ctype<uint64_t>, -- observation time (in microseconds)
value: number, -- current value
metric_name: string, -- metric name
},
-- another observation...
}
.. code-block:: lua
histogram_obj:collect{extended_format = true}
{
name: string, -- collector name
name_prefix: string, -- collector name_prefix
kind: string, -- collector kind
help: string, -- collector help
metainfo: table, -- collector metainfo
timestamp: ctype<uint64_t>, -- observation time (in microseconds)
observations = {
count = { -- map of count observations
-- an observation
key: string = {
label_pairs: table, -- `label_pairs` key-value table
value: number, -- current value
},
-- another observation...
},
sum = { -- map of sum observations
},
bucket = { -- map of bucket observations
},
}
}
.. method:: remove(label_pairs)

Expand Down Expand Up @@ -255,11 +344,61 @@ summary
Note that both label names and values in ``label_pairs``
are treated as strings.

.. method:: collect()
.. _metrics-api_reference-summary_collect:

.. method:: collect(opts)

:param table opts: table of collect options:

* ``extended_format`` -- use extended format in the output.

:return: A concatenation of ``observation`` objects for a given counter (by default or if
``extended format`` is ``false``). Otherwise returns a map with collector
description and structured observations.

.. code-block:: lua
summary_obj:collect{extended_format = false}
{
-- an observation
{
label_pairs: table, -- `label_pairs` key-value table
timestamp: ctype<uint64_t>, -- observation time (in microseconds)
value: number, -- current value
metric_name: string, -- metric name
},
-- another observation...
}
.. code-block:: lua
summary_obj:collect{extended_format = true}
{
name: string, -- collector name
name_suffix: string, -- collector name suffix
kind: string, -- collector kind
help: string, -- collector name
metainfo: table, -- collector metainfo
timestamp: ctype<uint64_t>, -- observation time (in microseconds)
observations = {
count = { -- map of count observations
-- an observation
key: string = {
label_pairs: table, -- `label_pairs` key-value table
value: number, -- current value
},
-- another observation...
},
sum = { -- map of sum observations
},
[''] = { -- map of quantile observations
},
}
}
Return a concatenation of ``counter_obj:collect()`` across all internal
counters of ``summary_obj``. For the description of ``observation``,
see :ref:`counter_obj:collect() <metrics-api_reference-counter_collect>`.
If ``max_age_time`` and ``age_buckets_count`` are set, quantile observations
are collected only from the head bucket in the sliding time window,
not from every bucket. If no observations were recorded,
Expand Down Expand Up @@ -375,6 +514,12 @@ Metrics functions

* ``invoke_callbacks`` -- if ``true``, ``invoke_callbacks()`` is triggerred before actual collect.
* ``default_only`` -- if ``true``, observations contain only default metrics (``metainfo.default = true``).
* ``extended_format`` -- if ``true``, collects extended format output from all collectors
(see :ref:`counter_obj:collect{extended_format = true} <metrics-api_reference-counter_collect>`,
:ref:`gauge_obj:collect{extended_format = true} <metrics-api_reference-gauge_collect>`,
:ref:`histogram_obj:collect{extended_format = true} <metrics-api_reference-histogram_collect>`,
:ref:`summary_obj:collect{extended_format = true} <metrics-api_reference-summary_collect>`)
and returns a map instead of an array.

.. class:: registry

Expand Down
78 changes: 16 additions & 62 deletions doc/monitoring/plugins.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -199,58 +199,6 @@ Use the JSON plugin with Tarantool ``http.server`` as follows:
end
)
.. _metrics-plugins-plugin-specific_api:

Plugin-specific API
-------------------

Use the following methods **only when developing a new plugin**.

.. module:: metrics

.. function:: invoke_callbacks()

Invoke a function registered via
``metrics.register_callback(<callback>)``.
Used in exporters.

.. function:: collectors()

List all collectors in the registry. Designed to be used in exporters.

:return: A list of created collectors.

.. class:: collector_object

.. method:: collect()

.. note::

You'll probably want to use ``metrics.collectors()`` instead.

Equivalent to:

.. code-block:: lua
for _, c in pairs(metrics.collectors()) do
for _, obs in ipairs(c:collect()) do
... -- handle observation
end
end
:return: A concatenation of ``observation`` objects across all created collectors.

.. code-block:: lua
{
label_pairs: table, -- `label_pairs` key-value table
timestamp: ctype<uint64_t>, -- current system time (in microseconds)
value: number, -- current value
metric_name: string, -- collector
}
:rtype: table

.. _metrics-plugins-custom:

Creating custom plugins
Expand All @@ -260,17 +208,23 @@ Include the following in your main export function:

.. code-block:: lua
-- Invoke all callbacks registered via `metrics.register_callback(<callback-function>)`
metrics.invoke_callbacks()
local metrics = require('metrics')
local string_utils = require('metrics.string_utils')
-- Loop over collectors
for _, c in pairs(metrics.collectors()) do
...
-- Collect up-to-date metrics with extended format.
local output = metrics.collect{invoke_callbacks = true, extended_format = true}
-- Loop over instant observations in the collector
for _, obs in pairs(c:collect()) do
-- Export observation `obs`
...
end
for _, coll_obs in pairs(output) do
-- Serialize collector info like coll_obs.name, coll_obs.help,
-- coll_obs.kind and coll_obs.timestamp
for group_name, obs_group in pairs(coll_obs.observations) do
-- Common way to build metric name.
local metric_name = string_utils.build_name(coll_obs.name, group_name)
for _, obs in pairs(obs_group) do
-- Serialize observation info: obs.value and obs.label_pairs
end
end
end
1 change: 1 addition & 0 deletions metrics-scm-1.rockspec
View file
Original file line number Diff line number Diff line change
Expand Up @@ -60,6 +60,7 @@ build = {
['metrics.utils'] = 'metrics/utils.lua',
['metrics.cfg'] = 'metrics/cfg.lua',
['metrics.stash'] = 'metrics/stash.lua',
['metrics.string_utils'] = 'metrics/string_utils.lua',
['cartridge.roles.metrics'] = 'cartridge/roles/metrics.lua',
['cartridge.health'] = 'cartridge/health.lua',
}
Expand Down
Loading

0 comments on commit 3740bba

Please sign in to comment.