{"id":20564318,"url":"https://github.com/tarantool/metrics-export-role","last_synced_at":"2025-04-14T15:10:49.935Z","repository":{"id":247594258,"uuid":"823087373","full_name":"tarantool/metrics-export-role","owner":"tarantool","description":"The Tarantool 3 role for metrics export via HTTP","archived":false,"fork":false,"pushed_at":"2025-04-08T16:56:04.000Z","size":59,"stargazers_count":1,"open_issues_count":7,"forks_count":2,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-04-08T17:49:56.139Z","etag":null,"topics":["lua","metrics","tarantool"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","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":"AUTHORS","dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-07-02T11:57:06.000Z","updated_at":"2025-01-14T08:07:22.000Z","dependencies_parsed_at":"2024-11-01T14:28:00.745Z","dependency_job_id":"308f90aa-b93b-4f1e-b782-ef39cc21ef49","html_url":"https://github.com/tarantool/metrics-export-role","commit_stats":null,"previous_names":["tarantool/metrics-export-role"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarantool%2Fmetrics-export-role","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarantool%2Fmetrics-export-role/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarantool%2Fmetrics-export-role/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tarantool%2Fmetrics-export-role/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tarantool","download_url":"https://codeload.github.com/tarantool/metrics-export-role/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248904640,"owners_count":21180835,"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":["lua","metrics","tarantool"],"created_at":"2024-11-16T04:25:37.406Z","updated_at":"2025-04-14T15:10:49.928Z","avatar_url":"https://github.com/tarantool.png","language":"Lua","readme":"\u003ca href='https://coveralls.io/github/tarantool/metrics-export-role?branch=master'\u003e\n\u003cimg src='https://coveralls.io/repos/github/tarantool/metrics-export-role/badge.svg?branch=master' alt='Coverage Status' /\u003e\n\u003c/a\u003e\n\n# metrics-export-role\n\n`roles.metrics-export` is a role for Tarantool 3. It allows to export metrics\nfrom Tarantool 3. For now only export via HTTP is supported.\n\n## Usage\n\n1. Add the `metrics-export-role` package to dependencies in the .rockspec file.\n\n```Lua\ndependencies = {\n    ...\n    'metrics-export-role == 0.3.0-1',\n    ...\n}\n```\n\nAnd re-build an application:\n\n```shell\ntt build\n```\n\nBe careful, it is better to use a latest release version.\n\n2. Enable and [configure](https://www.tarantool.io/en/doc/latest/concepts/configuration/)\nthe `roles.metrics-export` role for a Tarantool 3 instance. Use [httpd role](https://github.com/tarantool/http?tab=readme-ov-file#roles)\nor `listen` field in to configure server instances. See below to get more detailed information about it.\n\n```yaml\ngroups:\n  group-001:\n    replicasets:\n      replicaset-001:\n        instances:\n          master:\n            roles: [roles.httpd, roles.metrics-export]\n            roles_cfg:\n              roles.httpd:\n                default:\n                  listen: '127.0.0.1:8083'\n                additional:\n                  listen: 8084\n              roles.metrics-export:\n                http:\n                - endpoints:\n                  - path: /metrics/json\n                    format: json\n                - server: 'additional'\n                  endpoints:\n                  - path: /metrics/prometheus\n                    format: prometheus\n                - listen: 8081\n                  endpoints:\n                  - path: /metrics/json\n                    format: json\n                  - path: /metrics/prometheus/\n                    format: prometheus\n                - listen: 'my_host:8082'\n                  endpoints:\n                  - path: /metrics/prometheus\n                    format: prometheus\n                  - path: /metrics/json/\n                    format: json\n```\n\nIn the example above, we configure four HTTP servers. There are serveral server fields:\n\n* first with `server` field which refers to an `additional` server in the `httpd` role;\n* the next one, with no info about server, is configured with `default` name in `httpd` config;\n* and the last two `listen` fields (`0.0.0.0:8081` and `my_host:8082`) that are listed directly.\n\nThe servers will be running on the `master` Tarantool instance.\n\nEach server has two endpoints:\n\n* `/metrics/json` exports metrics with JSON format.\n* `/metrics/prometheus` exports metrics with Prometheus-compatible format.\n\n## Configuration\n\nThe role configuration at the top level could be described as:\n\n```yaml\nexport_target: opts\n```\n\n### http target\n\nFor now only `http` target is supported. The target allows to export metrics via\nHTTP-servers. The target could be configured as an array of servers.\n\nEach server must have `listen` param that could be a port (number) or a string\nin the format `host:port`. The address will be used by HTTP server to listen\nrequests.\n\nEach server could have `endpoints` param as an array of endpoints to process\nincoming requests. An individual endpoint can be described as:\n\n```yaml\n- path: /path/to/export/on/the/server\n  format: format_to_export\n```\n\nOptionally, you can enable\n[http metrics](https://www.tarantool.io/en/doc/latest/reference/reference_lua/metrics/#collecting-http-metrics)\nfor each endpoint. For this you should\nset `metrics.enabled` to `true`:\n\n```yaml\n- path: /path/to/export/on/the/server\n  format: format_to_export\n  metrics:\n    enabled: true\n```\n\nFor now only `json` and `prometheus` formats are supported.\n\n### Integration with httpd role\n\nUse [httpd role](https://github.com/tarantool/http?tab=readme-ov-file#roles) as well.\nTo enable it, you need to fill `server` field with name that was configured in `roles.httpd` block\ninstead of `listen` like it was earlier. To configure `httpd` role you need to write block in roles_cfg\nsection:\n\n```yaml\nroles_cfg:\n  roles.httpd:\n    default:\n      listen: 8081\n    additional:\n      listen: '127.0.0.1:8082'\n```\n\nAfter it you can use `server` name in `roles.metrics-export` block. If `server` and `listen` names\nwasn't provided, the `default` server from `httpd` role configuration will be used:\n\n```yaml\nroles.metrics-export:\n  http:\n  - server: 'additional'\n    endpoints:\n    ...\n  - endpoints:\n    ...\n```\n\nSo now it is possible to mix `server` and `listen` parameteres.\n\nLet's put it all together now:\n\n```yaml\nroles_cfg:\n  roles.httpd:\n    default:\n      listen: 8081\n    additional:\n      listen: '127.0.0.1:8082'\n  roles.metrics-export:\n    http:\n    - listen: 8081\n      endpoints:\n      - path: /metrics\n        format: json\n      - path: /metrics/prometheus/\n        format: prometheus\n    - listen: '127.0.0.1:8082'\n      endpoints:\n      - path: /metrics/\n        format: json\n        metrics:\n          enabled: true\n    - server: 'additional'\n      endpoints:\n      - path: /metrics\n        format: json\n    - endpoints:\n      - path: /metrics\n        format: prometheus\n        metrics:\n          enabled: true\n```\n\n### TLS support\n\nIt is possible to configure `metrics-export-role` with TLS options for\n`listen` parameter as well. To enable it, provide at least one of the\nfollowing parameters:\n\n    * `ssl_cert_file` is a path to the SSL cert file, mandatory;\n    * `ssl_key_file` is a path to the SSL key file, mandatory;\n    * `ssl_ca_file` is a path to the SSL CA file, optional;\n    * `ssl_ciphers` is a colon-separated list of SSL ciphers, optional;\n    * `ssl_password` is a password for decrypting SSL private key, optional;\n    * `ssl_password_file` is a SSL file with key for decrypting SSL private key, optional.\n\nSee an example below:\n\n```yaml\nroles_cfg:\n  roles.httpd:\n    default:\n      listen: 8081\n    additional:\n      listen: '127.0.0.1:8082'\n  roles.metrics-export:\n    http:\n    - listen: 8081\n      ssl_cert_file: \"/path/to/ssl_cert_file\"\n      ssl_key_file: \"/path/to/ssl_key_file\"\n      ssl_ca_file: \"/path/to/ssl_ca_file\"\n      ssl_ciphers: \"/path/to/ssl_ciphers\"\n      ssl_password: \"/path/to/ssl_password\"\n      ssl_password_file: \"/path/to/ssl_password_file\"\n      endpoints:\n      - path: /metrics\n        format: json\n      - path: /metrics/prometheus/\n        format: prometheus\n```\n\nWith this configuration, metrics can be obtained on this machine with the\nTarantool instance as follows:\n\n```shell\ncurl -XGET 127.0.0.1:8081/metrics\n# Metrics will be returned in JSON format.\ncurl -XGET 127.0.0.1:8081/metrics/prometheus\n# Metrics will be returned in Prometheus-compatible format.\ncurl -XGET 127.0.0.1:8082/metrics\n# Metrics will be returned in JSON format.\n```\n\n## Development\n\nFirst you need to clone the repository:\n\n```shell\ngit clone https://github.com/tarantool/metrics-export-role\ncd metrics-export-role\n```\n\nAfter that you need to install dependencies (`tt` is required).\nTo do it, run:\n\n```shell\nmake deps\n```\n\nIt's possible to install requirements only for running tests\nor linter check. To install only tests requirements, run:\n\n```shell\nmake deps depname=test\n```\n\nTo install tests with coverage requirements, run:\n\n```shell\nmake deps depname=coverage\n```\n\nTo install linter checks, run:\n\n```shell\nmake deps depname=lint\n```\n\nAt this point you could run tests (`tarantool` 3 is required):\n\n```shell\nmake test\n```\n\nAnd a linter:\n\n```shell\nmake luacheck\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftarantool%2Fmetrics-export-role","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftarantool%2Fmetrics-export-role","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftarantool%2Fmetrics-export-role/lists"}