{"id":13792621,"url":"https://github.com/tarantool/metrics","last_synced_at":"2025-09-12T22:40:07.045Z","repository":{"id":38366844,"uuid":"125366028","full_name":"tarantool/metrics","owner":"tarantool","description":"Metric collection library for Tarantool","archived":false,"fork":false,"pushed_at":"2024-04-19T11:32:38.000Z","size":1032,"stargazers_count":39,"open_issues_count":9,"forks_count":23,"subscribers_count":34,"default_branch":"master","last_synced_at":"2024-04-19T16:06:59.821Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tarantool.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2018-03-15T12:45:09.000Z","updated_at":"2024-04-23T13:56:58.248Z","dependencies_parsed_at":"2023-02-18T07:46:05.150Z","dependency_job_id":"3bb2b2bf-4ecd-4834-a489-5046869708a7","html_url":"https://github.com/tarantool/metrics","commit_stats":null,"previous_names":[],"tags_count":29,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarantool%2Fmetrics","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarantool%2Fmetrics/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarantool%2Fmetrics/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarantool%2Fmetrics/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tarantool","download_url":"https://codeload.github.com/tarantool/metrics/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224877034,"owners_count":17384699,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-03T22:01:14.419Z","updated_at":"2024-11-16T04:26:24.782Z","avatar_url":"https://github.com/tarantool.png","language":"Lua","funding_links":[],"categories":["Packages"],"sub_categories":["Administration"],"readme":"[![Build Status](https://github.com/tarantool/metrics/workflows/Tests/badge.svg?branch=master)](https://github.com/tarantool/metrics/actions)\n\n# Metrics\n\nMetrics is a library to collect and expose [Tarantool](https://tarantool.io)-based applications metrics.\n\nLibrary includes:\n- four base metric collectors: Counter, Gauge, Histogram, Summary\n- ready to use Tarantool stats collectors built on top of base collectors\n- exporters to expose collected metrics in Prometheus, Graphite and generic JSON format\n- module to integrate into Tarantool Cartridge based applications\n\n## Table of contents\n\n* [Installation](#installation)\n* [Plugins export](#plugins-export)\n* [Metric types](#metric-types)\n  * [Counter](#counter)\n  * [Gauge](#gauge)\n  * [Histogram](#histogram)\n  * [Summary](#summary)\n* [Next steps](#next-steps)\n* [Cartridge role](#cartridge-role)\n* [Contribution](#contribution)\n* [Contacts](#contacts)\n* [Credits](#credits)\n\n## Installation\n\n```bash\ncd ${PROJECT_ROOT}\ntt rocks install metrics\n```\n\n## Plugins export\n\nIn order to easily export metrics to any TSDB, you can use one of the supported\nexport plugins:\n\n- [Graphite](https://www.tarantool.io/en/doc/latest/book/monitoring/plugins/#graphite)\n- [Prometheus](https://www.tarantool.io/en/doc/latest/book/monitoring/plugins/#prometheus)\n- [Json](https://www.tarantool.io/en/doc/latest/book/monitoring/plugins/#json)\n\nor you can write your [custom plugin](https://www.tarantool.io/en/doc/latest/book/monitoring/plugins/#writing-custom-plugins) and use it.\nHopefully, plugins for other TSDBs will be supported soon.\n\n## Metric types\n\nThere are four basic metric collectors available: Counter, Gauge, Summary and Histogram.\nThe exact semantics of each metric follows the [prometheus metric types](https://prometheus.io/docs/concepts/metric_types/).\n\n### Counter\n\nCounter is a cummulative metric which value can only be incremented or reset to zero on restart.\nCounters are useful for accumulating number of events, e.g. requests processed, orders in e-shop.\nCounter is exposed as a single numerical value.\n\n```lua\nlocal metrics = require('metrics')\n\n-- create a counter\nlocal http_requests_total_counter = metrics.counter('http_requests_total')\n\n-- somewhere in HTTP requests middleware:\nhttp_requests_total_counter:inc(1, {method = 'GET'})\n```\n\n### Gauge\n\nGauge is a metric that represents a single numerical value that can be changed arbitrarily.\nGauges are useful for capturing a snapshot of the current state, e.g. CPU utilization, number of open connections.\nGauge is exposed as a single numerical value.\n\n```lua\nlocal metrics = require('metrics')\n\n-- create a gauge\nlocal cpu_usage_gauge = metrics.gauge('cpu_usage', 'CPU usage')\n\n-- register a lazy gauge value update\n-- this will be called whenever the export is invoked in any plugins\nmetrics.register_callback(function()\n    local current_cpu_usage = math.random()\n    cpu_usage_gauge:set(current_cpu_usage, {app = 'tarantool'})\nend)\n```\n\n### Histogram\n\nHistogram counts observed values into configurable buckets.\nHistograms are useful for tracking request latencies, processing time.\nHistogram is exposed as multiple numerical values:\n- the total count of observed events\n- the total sum of observed values\n- counters of observed events per bucket\n\n```lua\nlocal metrics = require('metrics')\n\n-- create a histogram\nlocal http_requests_latency_hist = metrics.histogram(\n    'http_requests_latency', 'HTTP requests total', {2, 4, 6})\n\n-- somewhere in the HTTP requests middleware:\nlocal latency = math.random(1, 10)\nhttp_requests_latency_hist:observe(latency)\n```\n\n### Summary\n\nSummary aggregates observed values into configurable quantiles.\nSummaries are useful as a service level indicator (e.g. SLAs, SLOs).\nSummary is exposed as multiple numerical values:\n- the total count of observed events\n- the total sum of observed values\n- number of observed events per quantile\n\n```lua\nlocal metrics = require('metrics')\n\n-- create a summary with a sliding window of 5 age buckets and 60s bucket lifetime\nlocal http_requests_latency = metrics.summary(\n    'http_requests_latency', 'HTTP requests total',\n    {[0.5]=0.01, [0.9]=0.01, [0.99]=0.01},\n    {max_age_time = 60, age_buckets_count = 5}\n)\n\n-- somewhere in the HTTP requests middleware:\nlocal latency = math.random(1, 10)\nhttp_requests_latency:observe(latency)\n```\n\n### Instance health check\n\nIn production environments Tarantool Cluster usually has a large number of so called \"routers\", Tarantool instances that handle input load and it is required to evenly distribute the load. Various load-balancers are used for this, but any load-balancer have to know which \"routers\" are ready to accept the load at that very moment. Metrics library has a special plugin that creates an http handler that can be used by the load-balancer to check the current state of any Tarantool instance. If the instance is ready to accept the load, it will return a response with a 200 status code, if not, with a 500 status code.\n\n## Next steps\n\nSee:\n\n- A more detailed [getting started guide](https://www.tarantool.io/en/doc/latest/book/monitoring/getting_started/)\n- Metrics [API reference](https://www.tarantool.io/en/doc/latest/book/monitoring/api_reference/)\n- Detailed information on [plugins](https://www.tarantool.io/en/doc/latest/book/monitoring/plugins)\n\n## Contribution\n\nFeel free to send Pull Requests.\nTo increase the chance of having your pull request accepted, make sure it follows these guidelines:\n\n- Title and description matches the implementation.\n- Code follows [styleguide](https://www.tarantool.io/en/doc/latest/dev_guide/lua_style_guide/).\n- The pull request closes one or more of related issues. If not, please add an issue first.\n- The pull request contains necessary tests that verify the intended behavior.\n- The pull request contains a CHANGELOG note and documentation update if needed.\n\nYour pull request will be reviewed in 3-5 days.\n\n## Contacts\n\nIf you have questions, please ask it on [StackOverflow](https://stackoverflow.com/questions/tagged/tarantool) or contact us in Telegram:\n\n- [Russian-speaking chat](https://t.me/tarantoolru)\n- [English-speaking chat](https://t.me/tarantool)\n\n## Credits\n\nWe would like to thank Prometheus for a great API that we brusquely borrowed.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftarantool%2Fmetrics","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftarantool%2Fmetrics","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftarantool%2Fmetrics/lists"}