{"id":20980689,"url":"https://github.com/statful/statful-client-nodejs","last_synced_at":"2025-05-14T15:30:49.853Z","repository":{"id":10079489,"uuid":"64384149","full_name":"statful/statful-client-nodejs","owner":"statful","description":"Statful client for NodeJS applications. This client is intended to gather metrics and send them to Statful. ","archived":false,"fork":false,"pushed_at":"2022-12-30T20:21:18.000Z","size":461,"stargazers_count":8,"open_issues_count":7,"forks_count":9,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-21T04:54:30.551Z","etag":null,"topics":["javascript","metrics","nodejs","performance","statful"],"latest_commit_sha":null,"homepage":"https://www.statful.com","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"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":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-07-28T09:54:08.000Z","updated_at":"2021-05-13T06:50:05.000Z","dependencies_parsed_at":"2023-01-13T15:44:03.031Z","dependency_job_id":null,"html_url":"https://github.com/statful/statful-client-nodejs","commit_stats":null,"previous_names":[],"tags_count":20,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statful%2Fstatful-client-nodejs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statful%2Fstatful-client-nodejs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statful%2Fstatful-client-nodejs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/statful%2Fstatful-client-nodejs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/statful","download_url":"https://codeload.github.com/statful/statful-client-nodejs/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254171594,"owners_count":22026470,"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":["javascript","metrics","nodejs","performance","statful"],"created_at":"2024-11-19T05:29:38.627Z","updated_at":"2025-05-14T15:30:48.867Z","avatar_url":"https://github.com/statful.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\nStatful Client for NodeJS\n==============\n\n[![NPM version][npm-image]][npm-url] [![Build Status](https://travis-ci.org/statful/statful-client-nodejs.svg?branch=master)](https://travis-ci.org/statful/statful-client-nodejs)\n\nStatful client for NodeJS written in Javascript. This client is intended to gather metrics and send them to Statful.\n\n## Table of Contents\n\n* [Supported Versions of NodeJS](#supported-versions-of-nodejs)\n* [Installation](#installation)\n* [Quick Start](#quick-start)\n* [Reference](#reference)\n  * [Global Configuration](#global-configuration)\n  * [Methods](#methods)\n  * [Plugins](#plugins)\n* [Examples](#examples)\n  * [UDP Configuration](#udp-configuration)\n  * [HTTP Configuration](#http-configuration)\n  * [Logger Configuration](#logger-configuration)\n   * [Configuration of Defaults per Method](#configuration-of-defaults-per-method)\n  * [Preset Configuration](#preset-configuration)\n  * [Send Metrics Configuration](#send-metrics-configuration)\n * [Authors](#authors)\n* [License](#license)\n\n## Supported Versions of NodeJS\n\n| Statful Client version | Tested NodeJS versions  |\n|:---|:---|\n| 4.x.x | `4.4.0`, `5.12.0`, `6.9.2`, `7.10.1`, `8.2.0` |\n| 5.x.x | `6.9.2`, `7.10.1`, `8.2.0`, `10.9.0` |\n| 6.x.x | `8.2.0`, `8.12.0`, `10.12.0`, `11.0.0` |\n\n## Installation\n\nFirst, install Statful’s NodeJS Client into your System, in the same path as your JS file, by executing the below command:\n\n```bash\n$ npm install statful-client --save\n```\n\n## Quick Start\n\nAfter installing Statful’s NodeJS Client, you are ready to push your metric into Statful by adding the below code into your JS file:\n\n```javascript\nvar Statful = require('statful-client');\n\n// Creates an object with the desired configuration and pass it to the client\nvar config = {\n    app: 'AccountService',\n    transport: 'api',\n    api: {\n        token: 'STATFUL_API_TOKEN'        \n    },\n    tags: { cluster: 'production' }\n};\nvar statful = new Statful(config);\n\n// Send a `counter` metric\nstatful.counter('transactions', 1);\n```\n\n\u003e **IMPORTANT:**\u003cbr\u003e**host** / **port:** Default values are set for _host_ and _port_, based on whether the 'transport' attribute is set to _udp_ or _api_. (Refer the below table for the default values). However, it is possible to override the default values, by manually specifying the desired values within the Object (_udp_ or _api_ as applicable)\u003cbr\u003e**token:** Your _token_ value is available in the 'Api Tokens' page of your Statful account.\u003cbr\u003e\u003cbr\u003e[More configurations are available in the [Examples](#examples) section].\n\n## Reference\n\nThe following section presents a detailed reference of the available options to take full advantage of Statful.\n\n### Global Configuration\n\nBelow you can find the information on the custom options to set up the configurations parameters.\n\n| Option | Description | Type | Default | Required |\n|:---|:---|:---|:---|:---|\n| _app_ | Defines the application's global name. When specified, it sets a global tag like `app=setValue`. | `string` | **none** | **NO** |\n| _default_ | Object for setting methods' options. | `object` | `{}` | **NO** |\n| _api_ | Object for setting API configurations: authentication and timeout. | `object` | **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| _flushInterval_ | Defines the periodicity of buffer flushes in **milliseconds**. | `number` | `3000` | **NO** |\n| _flushSize_ | Defines the maximum buffer size before performing a flush, in **milliseconds**. | `number` | `1000` | **NO** |\n| _namespace_ | Defines the global namespace. A prefix could be set if the user sends metrics through Statful. | `string` | `application` | **NO** |\n| _sampleRate_ | Defines the rate sampling. **It should be a number between [1, 100]**. | `number` | `100` | **NO** |\n| _tags_ | Object for setting the global tags. | `object` | `{}` | **NO** |\n| _transport_ | Defines the transport layer to be used to send metrics.\u003cbr\u003e\u003cbr\u003e **Valid Transports:** `udp, api` | `string` | **none** | **YES** |\n| _host_ | Defines the hostname to where the metrics are sent. It can be set for _api_ or _udp_ based on the 'transport' value. | `string` | udp:   `127.0.0.1`\u003cbr\u003eapi: `'api.statful.com'` | **NO** |\n| _path_ | Defines the API path to where the metrics are sent. It can only be set inside _api_. | `string` | `/tel/v2.0/metric` | **NO** |\n| _port_ | Defines the port where the metrics are sent. It can be set for _api_ or _udp_ based on the 'transport' value. | `string` | udp: `2013`\u003cbr\u003eapi: `443` | **NO** |\n| _token_ | Defines the token used to match incoming data to Statful. It can only be set inside _api_. | `string` | **none** | **YES** |\n| _timeout_ | Defines the timeout for the transport layers in **milliseconds**. It can only be set inside _api_. | `number` | `2000` | **NO** |\n\n### Methods\n\n```javascript\n// Non-Aggregated Metrics\n- statful.counter('myCounter', 1, {agg: ['sum']});\n- statful.gauge('myGauge', 10, { tags: { host: 'localhost' } });\n- statful.timer('myCounter', 200, {namespace: 'sandbox'});\n- statful.put('myCustomMetric', 200, {timestamp: '1471519331'});\n\n// Aggregated Metrics\n- statful.aggregatedCounter('myCounter', 1, 'avg', 60, { tags: { host: 'localhost' } });\n- statful.aggregatedGauge('myGauge', 10, 'avg', 60, { tags: { host: 'localhost' } });\n- statful.aggregatedTimer('myCounter', 200, 'avg', 60, {namespace: 'sandbox'});\n- statful.aggregatedPut('myCustomMetric', 200, 'avg', 60, {timestamp: '1471519331'});\n```\nThe methods for non-aggregated metrics receive a metric name and value as arguments and send a counter, a gauge, a timer or a custom metric.\n\nThe methods for aggregated metrics receive a metric name and value, an aggregation and an aggregation frequency (the one used beforehand to aggregate the metric) as arguments, and send a counter, a gauge, a timer or a custom metric. Whenever the options parameter is left out, the default values are used instead.\n\nThe latter methods are a valuable asset to address the need of ingestion of already aggregated metrics into Statful (for example, aggregated metrics from AWS CloudWatch). For more information about the default values, read the methods options' reference presented next.\n\n\u003e **IMPORTANT:** You can only send aggregated metrics with an `api` transport type. Otherwise, the metrics are discarded, and they will not be sent.\n\n| Description | Default for Counter | Default for Gauge | Default for Timer | Default for Put | Available for Aggregated Methods |\n|:---|:---|:---|:---|:---|:---|\n| **_agg_** (`array`)  - Defines the aggregations to execute. These aggregations are merged with the ones configured globally, including method defaults.\u003cbr\u003e\u003cbr\u003e **Valid Aggregations:** `avg, count, sum, first, last, p90, p95, p99, min, max` | `['sum', 'count']` | `['last']` | `['avg', 'p90', 'count']` | `[]` | **NO** |\n| **_aggFreq_** (`number`) - Defines the aggregation frequency, in **seconds**. It overrides the global aggregation frequency configuration.\u003cbr\u003e\u003cbr\u003e **Valid Aggregation Frequencies:** `10, 30, 60, 120, 180, 300` | `10` | `10` | `10` | `10` | **NO** |\n| **_namespace_** (`string`)  - Defines the namespace of the metric. It overrides the global namespace configuration. | `application` | `application` | `application` | `application` | **YES** |\n| **_tags_** (`object`) - Defines the tags of the metric. These tags are merged with the ones configured globally, including method defaults. | `{}` | `{}` | `{ unit: 'ms' }` | `{}` | **YES** |\n| **_timestamp_** (`string`)  - Defines the timestamp of the metric. This timestamp is a **UNIX Epoch** time, represented in **seconds**.  | `current timestamp` | `current timestamp` | `current timestamp` | `current timestamp` | **YES** |\n\n## Plugins\n\n### System Stats Plugin\n\nThis plugin allows the client to send system-related metrics and to enrich the user's metrics with system tags.\n\nIt is possible to use this plugin with the client as follows:\n```javascript\n    var SystemStatsPlugin = require('statful-client').systemStatsPlugin;\n    var statful = new Statful(config, log);\n    statful.use(new SystemStatsPlugin());\n```\n\n#### System Stats Plugin Configuration\n\nThe custom options available to set on config param are detailed below.\n\n| Option | Display name | Description | Type | Default | Required |\n|:---|:---|:---|:---|:---|:---|\n| _bufferFlushLength_ | `.buffler.flush_length` | Length of the queue on flush events | `number` | **none**| **NO** |\n| _timerEventLoop_ | `.timer.event_loop` | Time spent to execute the callback in **milliseconds** | `number` | **none**| **NO** |\n| _processUptime_ | `.process.uptime` | Uptime of the process in **milliseconds** | `number` | **none**| **NO** |\n| _processMemoryUsage_ | `process.memory.usage` | Process memory usage in **bytes** | `number` | **none**| **NO** |\n| _processMemoryUsagePerc_ | `process.memory.usage.perc` | Process memory usage in **percentage** (compared to total OS memory) | `number` | **none**| **NO** |\n| _osUptime_ | `.os.uptime` | OS uptime in **milliseconds** | `number` | **none**| **NO** |\n| _osTotalMemory_ | `.os.memory.total` | OS total memory in **bytes** | `number` | **none**| **NO** |\n| _osFreeMemory_ | `os.memory.free` | OS free memory in **bytes** | `number` | **none**| **NO** |\n| _tagHostname_ | `hostname` | Hostname | `string` | **none**| **NO** |\n| _tagPlatform_ | `platform` | Platform | `string` | **none**| **NO** |\n| _tagArchitecture_ | `architecture` | Architecture | `string` | **none**| **NO** |\n| _tagNodeVersion_ | `node_version` | NodeJS Version | `string` | **none**| **NO** |\n\n## Examples\n\nHere you can find some useful usage examples of the Statful’s NodeJS Client. In the following examples, we assume that you have already installed and included the Statful Client in your project with success.\n\n### UDP Configuration\n\nCreate a simple UDP configuration for the client.\n\n```javascript\nvar Statful = require('statful-client');\n\nvar config = {\n    app: 'AccountService',\n    transport: 'udp',\n    host: 'statful-relay.yourcompany.com',\n    tags: { cluster: 'production' }\n};\n\nvar statful = new Statful(config);\n```\n\n### HTTP Configuration\n\nCreate a simple HTTP API configuration for the client.\n\n```javascript\nvar Statful = require('statful-client');\n\nvar config = {\n    app: 'AccountService',\n    transport: 'api',\n    api: {\n        token: 'STATFUL_API_TOKEN'\n    },\n    tags: { cluster: 'production' }\n};\n\nvar statful = new Statful(config);\n```\n\n### Logger configuration\n\nCreate a simple client configuration to add your favorite logger to the client such as Bunyan, Winston or others. **The only requirement is to make sure that the chosen logger object supports: log, info, warn, debug and error methods.**\n\n```javascript\nvar Statful = require('statful-client');\nvar logger = require('your-favourite-logging-lib');\n\nvar config = {\n    app: 'AccountService',\n    transport: 'api',\n    api: {\n        token: 'STATFUL_API_TOKEN'\n    },\n    tags: { cluster: 'production' }\n};\n\nvar statful = new Statful(config, logger);\n```\n\n### Configuration of Defaults per Method\n\nCreate a configuration for the client where you define custom default options per method.\n\n```javascript\nvar Statful = require('statful-client');\n\nvar config = {\n    default: {\n        counter: { agg: ['avg'], aggFreq: 180 },\n        gauge: { agg: ['first'], aggFreq: 180 },\n        timer: { tags: { cluster: 'qa' }, agg: ['count'], aggFreq: 180 }\n    },\n    tags: { cluster: 'production' },\n    api: {\n        token: 'STATFUL_API_TOKEN'\n    },\n    transport: 'api'\n}\n\nvar statful = new Statful(config);\n```\n\n### Preset Configuration\n\nCreate a configuration where you define a value for currently available options.\n\n```javascript\nvar Statful = require('statful-client');\n\nvar config = {\n    default: {\n        timer: { tags: { cluster: 'qa' }, agg: ['count'], aggFreq: 180 }\n    },\n    dryRun: true,\n    flushInterval: 5000,\n    flushSize: 50,\n    transport: 'api',\n    api: {\n        timeout: 300,\n        token: 'STATFUL_API_TOKEN'\n    },\n    namespace: 'application',\n    tags: { cluster: 'production' }\n}\n\nvar statful = new Statful(config);\n```\n\n### Send Metrics Configuration\n\nCreate a simple client configuration to send a few metrics.\n\n```javascript\nvar Statful = require('statful-client');\n\nvar config = {\n    app: 'AccountService',\n    transport: 'udp',\n    host: 'statful-relay.yourcompany.com',\n    tags: { cluster: 'production' }\n};\n\nvar statful = new Statful(config);\n\n// Send three different metrics (gauge, timer and counter)\nstatful.gauge('testGauge', 10);\nstatful.timer('testTimer', 100);\nstatful.counter('testCounter', 1, { agg: ['first'], aggFreq: 60, namespace: 'sandbox' });\n\n// Send a metric with custom tags\nstatful.counter('testCounter', 1, {tags: {host: 'localhost', status: 'SUCCESS'}});\n```\n\n## Authors\n\n[Mindera - Software Craft](https://github.com/Mindera)\n\n## License\n\nStatful NodeJS Client is available under the MIT license. See the [LICENSE](https://raw.githubusercontent.com/statful/statful-client-objc/master/LICENSE) file for more information.\n\n[npm-url]: https://npmjs.org/package/statful-client\n[npm-image]: https://badge.fury.io/js/statful-client.svg\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstatful%2Fstatful-client-nodejs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstatful%2Fstatful-client-nodejs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstatful%2Fstatful-client-nodejs/lists"}