{"id":20980687,"url":"https://github.com/statful/statful-client-vertx","last_synced_at":"2025-05-14T15:30:50.032Z","repository":{"id":57727279,"uuid":"73190745","full_name":"statful/statful-client-vertx","owner":"statful","description":"Statful client for Vertx applications. This client is intended to gather metrics and send them to Statful.","archived":false,"fork":false,"pushed_at":"2019-08-16T09:57:28.000Z","size":238,"stargazers_count":5,"open_issues_count":6,"forks_count":3,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-02T20:06:10.198Z","etag":null,"topics":["metrics","performance","statful","vertx"],"latest_commit_sha":null,"homepage":"https://www.statful.com/","language":"Java","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/statful.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-11-08T13:56:08.000Z","updated_at":"2019-08-16T09:56:46.000Z","dependencies_parsed_at":"2022-09-26T20:22:01.928Z","dependency_job_id":null,"html_url":"https://github.com/statful/statful-client-vertx","commit_stats":null,"previous_names":[],"tags_count":12,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statful%2Fstatful-client-vertx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statful%2Fstatful-client-vertx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statful%2Fstatful-client-vertx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statful%2Fstatful-client-vertx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/statful","download_url":"https://codeload.github.com/statful/statful-client-vertx/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254171592,"owners_count":22026469,"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":["metrics","performance","statful","vertx"],"created_at":"2024-11-19T05:29:38.106Z","updated_at":"2025-05-14T15:30:48.604Z","avatar_url":"https://github.com/statful.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"Statful Client for Vert.x\n==============\n\n[![Build Status](https://travis-ci.org/statful/statful-client-vertx.svg?branch=master)](https://travis-ci.org/statful/statful-client-vertx)\n\nStatful client for Vert.x written in Java. This client enables pushing custom metrics as well as metrics collection for [Vert.x](http://vertx.io/) based projects and sends them to [Statful.](http://statful.com/)\n\nThis client leverages the capabilities provided by [Vert.x SPI](http://vertx.io/docs/apidocs/io/vertx/core/spi/metrics/VertxMetrics.html) to collect metrics.\n\nPlease check the project’s [pom.xml](https://github.com/statful/statful-client-vertx/blob/master/pom.xml) file to see the current Vert.x version dependency since we always aim to support the latest stable version.\n\n## Table of Contents\n\n* [Supported Versions](#supported-versions)\n* [Requirements](#requirements)\n* [Quick Start](#quick-start)\n\t* [Programmatically](#programmatically)\n\t* [Configuration File](#configuration-file)\n* [Configurations](#configurations)\n\t* [Global Configurations](#global-configurations)\n\t* [Statful's Configurations Specific to Vert.x](#statfuls-configurations-specific-to-vert.x)\n* [Usage](#usage)\n\t* [Custom Metrics](#custom-metrics)\n\t* [Metrics Collection](#metrics-collection)\n* [Limitations](#limitations)\n* [Authors](#authors)\n* [License](#license)\n\n## Supported Versions\n\n| Statful Client version | Tested Java versions  | Tested Vert.x versions\n|:---|:---|:---|\n| 1.x.x | `Java 8` | `3.4.2` |\n\n## Requirements\n\nThis client has the following requirement:\n\n* [Vert.x](http://vertx.io/) \n\n## Quick Start\n\nAdd the client to the project dependencies:\n\n    \u003cdependency\u003e\n       \u003cgroupId\u003ecom.statful.client\u003c/groupId\u003e\n       \u003cartifactId\u003eclient-vertx\u003c/artifactId\u003e\n      \u003cversion\u003e${version-number}\u003c/version\u003e\n    \u003c/dependency\u003e\n\nVert.x handles the creation of the Metrics Service Provider Interface ([SPI](https://vertx.io/docs/vertx-core/java/#_metrics_spi)).\n\nFrom this point, you can set up the client in two ways, programmatically or by using a configuration file.\n\n### Programmatically\n\nCreate an instance of *StatfulMetricsOptions* and set all the desired parameters. Use the configured instance as an argument for *VertxOptions* when creating the *Vertx* instance.\n\nSet the `StatfulMetricsFactoryImpl` factory to be used by the Metrics SPI.\n\nExample:\n\n    StatfulMetricsOptions options = new StatfulMetricsOptions()\n            .setEnabled(true)\n            .setFactory(new StatfulMetricsFactoryImpl());\n            \n    VertxOptions vertxOptions = new VertxOptions().setMetricsOptions(options);\n    Vertx vertx = Vertx.vertx(vertxOptions);\n    \nWhen using a custom `Launcher` that implements the `VertxLifecycleHooks` interface, it’s expected of the user to override the `beforeStartingVertx` method.\n\nExample:\n\n    @Override\n    public void beforeStartingVertx(VertxOptions options) {\n        options.setMetricsOptions(new StatfulMetricsOptions()\n                .setEnabled(true)\n                .setFactory(new StatfulMetricsFactoryImpl()));\n    }\n\n### Configuration File\n\nYou need to provide two parameters when launching your application, one to enable metrics and another to set the configuration file. Enabling metrics triggers *Vertx* to init the metrics system which will then read the configuration file.\n\nExample:\n\n    -Dvertx.metrics.options.enabled=true -Dvertx.metrics.options.configPath=config/statful.json\n\nThe configuration file is a simple JSON document, like the sample shown below:\n\n    {\n      \"host\": \"api.statful.com\",\n      \"port\": 443,\n      \"transport\": \"HTTP\",\n      \"httpMetricsPath\": \"/tel/v2.0/metrics\",\n      \"secure\": true,\n      \"app\": \"application\",\n      \"dryrun\": false,\n      \"sampleRate\": 100,\n      \"namespace\": \"namespace\",\n      \"timerAggregations\": [\n        \"AVG\",\n        \"COUNT\"\n      ],\n      \"counterAggregations\": [],\n      \"timerFrequency\": \"FREQ_10\",\n      \"enabled\": true,\n      \"http-server-url-patterns\": [\n        {\n          \"pattern\": \"\\\\w{8}-\\\\w{4}-\\\\w{4}-\\\\w{4}-\\\\w{12}\",\n          \"replacement\": \"_uuid_\"\n        }\n      ],\n      \"http-server-ignore-url-patterns\": [\n        \"/static/.*\"\n      ],\n      \"collectors\": {\n        \"pool\": true,\n        \"httpClient\": false,\n        \"httpServer\": true\n      }\n    }\n\n## Configurations\nThe following section presents detailed information on the available options for setup in the configuration parameters.\n\n### Global Configurations\n\n| Option | Description | Type | Default | Required |\n|:---|:---|:---|:---|:---|\n| _host_ | Defines the hostname to where the metrics are sent. | `string` | `api.statful.com` | **NO** |\n| _port_ | Defines the port to where the metrics are sent. | `string` | `443` | **NO** |\n| _secure_ | Enables or disables https. | `boolean` | `true` | **NO** |\n| _timeout_ | Defines the timeout for http transport, in **milliseconds**.\u003cbr\u003e\u003cbr\u003eNot yet supported. | `number` | `2000` | **NO** |\n| _token_ | Defines the token used to match incoming data to Statful.| `string` | **none** | **YES** |\n| _app_ | Defines the application's global name. When specified, it sets a global tag like `app=setValue`. | `string` | **none** | **NO** |\n| _dryRun_ | Defines if metrics should be output to the logger instead of being sent to Statful (useful for testing/debugging purposes). | `boolean` | `false` | **NO** |\n| _tags_ | Object for setting the global tags. | `object` | `{}` | **NO** |\n| _sampleRate_ | Defines the rate sampling. \u003cbr\u003e\u003cbr\u003e**It should be a number between [1, 100]**. | `number` | `100` | **NO** |\n| _namespace_ | Defines the global namespace. A prefix could be set if the user sends metrics through Statful. | `string` | `application` | **NO** |\n| _flushSize_ | Defines the maximum buffer size before performing a flush. | `number` | `10` | **NO** |\n| _flushInterval_ | Defines an interval to periodically flush the buffer based on time. | `number` | `30000` | **NO** |\n| _maxBufferSize_ | Defines how many metrics at max are kept in the buffer between forced flushes. | `number` | `5000` | **NO** |\n\n\n### Statful's Configurations Specific to Vert.x\n\n| Option | Description | Type | Default | Required |\n|:---|:---|:---|:---|:---|\n| _enabled_ | Enables or disables the client. | `boolean` | `true` | **NO** |\n| _timerAggregations_ | Defines the aggregations to apply to timer-based metrics. | `string` | `[Aggregation.AVG, Aggregation.P90, Aggregation.COUNT]` | **NO** |\n| _counterAggregations_ | Defines the aggregations to apply to counter-based metrics. | `string` | `[Aggregation.COUNT, Aggregation.SUM]` | **NO** |\n| _counterFrequency_ | Defines the aggregation frequency for counter-based metrics. | `string` | `[AggregationFreq.FREQ_10]` | **NO** |\n| _gaugeAggregations_ | Defines the aggregations to apply to gauge-based metrics. | `string` | ` [Aggregation.LAST, Aggregation.MAX, Aggregation.AVG]` | **NO** |\n| _gaugeFrequency_ | Defines the aggregation frequency for gauge-based metrics. | `string` | `[AggregationFreq.FREQ_10]` | **NO** |\n| _http-server-url-patterns_ | Defines patterns to transform URLs for metrics collection. | `string` | **none** | **NO** |\n| _http-server-ignore-url-patterns_ | Defines patterns of URLs that you don't want to be tracked. | `string` | **none** | **NO** |\n| _gauge-reporting-interval_ | Defines the value for gauge reporting in **milliseconds.** | `number` | `5000` | **NO** |\n| _httpMetricsPath_ | Defines the path to send metrics when the http transport is set. | `string` | `/tel/v2.0/metrics` | **NO** |\n| _transport_ | Defines the transport type to use when sending metrics to Statful. \u003cbr\u003e\u003cbr\u003e**Valid Transports:**`UDP, HTTP`| `string` | `HTTP` | **NO** |\n\n\u003e To disable aggregations for a type of metric, set the value of the aggregations' configuration to an empty list.\n    \n#### Metric collectors\nTo enable metric collection, you must set the option with the flags of the available collectors.\n\n| Option | Description | Type | Default | Required |\n|:---|:---|:---|:---|:---|\n| _collectors_ | Object to employ metric collectors. | `object` | **none** | **NO** |\n     \nList of available collectors:\n\n| Option | Description | Type | Default | Required |\n|:---|:---|:---|:---|:---|\n| _pool_ | Enables the collection of metrics from application pools. | `boolean` | `false` | **NO** |\n| _httpClient_ | Enables the collection of metrics from http clients. | `boolean` | `false` | **NO** |\n| _httpServer_ | Enables the collection of metrics from http servers. | `boolean` | `false` | **NO** |\n\n\n## Usage\n\n### Custom Metrics\n\nTo save custom metrics, send a message to the *eventBus* such as:\n\n    EventBus eventBus = vertx.eventBus();\n    eventBus.send(CustomMetricsConsumer.ADDRESS, \n        new CustomMetric.Builder()\n            .withMetricName(getMetric()) // String\n            .withValue(getValue()) // long\n            .withTimestamp(getTimestamp()) // EpochSecond\n            .withTags(getTags())\n            .build();\n\nA `CustomMetricsConsumer` subscribes to the `CustomMetricsConsumer.ADDRESS` and is responsible for saving the metrics to the in-memory buffer.\n\nOnly the `metricName` and `value` are required for a valid metric. Please refer to the `CustomMetric` class for more details. \n    \n### Metrics Collection\n\n#### Http Client\n\nTrack the time that takes to execute each request and its response status code. Currently, the connection time is not reported.\n\nTo identify a request that you want to track, add a request header to that request. The pattern used to recognize and extract the request header is *Tags.TRACK_HEADER*, where its value (of the header) should be set to the desired value at the *com/statful/tag/Tags.java* file.\n\n#### Http Server\n\nBy default, all requests are tracked. To ignore a path, configure a regex that matches that path. For instance, to ignore a request that starts with */static* apply the following configuration:\n\n    \"http-server-ignore-url-patterns\": [\n      \"\\/static\\/.*\"\n    ]\n\nURLs are used as tag values. To avoid creating tags with IDs, or any other unexpected identifier from your URLs, you can configure the transformation regex to be applied. Here’s an example of how to remove UUIDs from the URLs on a restful API:\n\n    \"http-server-url-patterns\": [\n      {\n        \"pattern\": \"\\\\w{8}-\\\\w{4}-\\\\w{4}-\\\\w{4}-\\\\w{12}\",\n        \"replacement\": \"_uuid_\"\n      }\n    ]\n\nThis configuration transforms:\n\n    /user/095b1cac-c153-4c6b-a09c-1bd4a1220019/update\n\nInto:\n\n    /user_uuid_/update\n\n\u003e Please keep in mind that any regex will be applied to all existing URLs so, the more regex there are to be applied, the heavier the execution will be.\n\n#### Pools\n\nIt’s possible to track *Vertx* *ConnectionPool* usage metrics.\n\n\n## Limitations\n\nThe current implementation has the following limitation:\n\n* It does not support http2 metrics introduced by Vert.x version 3.3.0.\n\n## Authors\n\n[Mindera - Software Craft](https://github.com/Mindera)\n\n## License\n\nStatful's Vert.x Client is available under the MIT license. See the [LICENSE](https://raw.githubusercontent.com/statful/statful-client-vertx/master/LICENSE) file for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstatful%2Fstatful-client-vertx","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstatful%2Fstatful-client-vertx","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstatful%2Fstatful-client-vertx/lists"}