https://github.com/statful/statful-client-javascript
Statful client for Javascript. This client is intended to gather metrics and send them to Statful.
https://github.com/statful/statful-client-javascript
gather-metrics javascript metrics performance statful
Last synced: 9 months ago
JSON representation
Statful client for Javascript. This client is intended to gather metrics and send them to Statful.
- Host: GitHub
- URL: https://github.com/statful/statful-client-javascript
- Owner: statful
- License: mit
- Created: 2016-07-28T16:02:21.000Z (almost 10 years ago)
- Default Branch: master
- Last Pushed: 2023-03-04T02:39:30.000Z (over 3 years ago)
- Last Synced: 2025-08-19T14:36:02.909Z (10 months ago)
- Topics: gather-metrics, javascript, metrics, performance, statful
- Language: JavaScript
- Homepage: https://www.statful.com/
- Size: 3.69 MB
- Stars: 8
- Watchers: 5
- Forks: 4
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# statful-client-javascript
Statful client for Javascript. This client is intended to gather metrics and send them to Statful.
[](https://travis-ci.org/statful/statful-client-javascript)
[](https://david-dm.org/statful/statful-client-javascript#info=devDependencies)
[](https://packagephobia.now.sh/result?p=statful-client-javascript)
## Table of Contents
* [Supported Versions](#supported-versions)
* [Installation](#installation)
* [Quick Start](#quick-start)
* [Reference](#reference)
* [Authors](#authors)
* [License](#license)
## Supported Versions
It supports every browser that has full support for the ECMAScript 5 specification.
## Installation
```
npm install --save statful-client-javascript
```
or
```
bower install --save statful-client-javascript
```
## Quick Start
After installing Statful Client you are ready to use it. The quickest way is to do the following:
```javascript
// Init statful
statful.initialize({
dryrun: false,
debug: false,
app: 'exampleApp',
flushInterval: 5000
});
// Send a metric
statful.counter('page_load');
```
## Reference
Reference if you want to take full advantage from Statful.
### Global configuration
The custom options that can be set on config param are detailed below.
| Option | Description | Type | Default | Required |
|:---|:---|:---|:---|:---|
| dryRun | Defines if metrics should be output to the logger instead of being send. | `boolean` | `false` | **NO** |
| debug | Defines logs should be sent to console. | `boolean` | `false` | **NO** |
| app | Defines the application global name. If specified sets a global tag `app=setValue`. | `string` | **undefined** | **NO** |
| namespace | Defines the global namespace. | `string` | `web` | **NO** |
| sampleRate | Defines the rate sampling. **Should be a number between [1, 100]**. | `number` | `100` | **NO** |
| flushInterval | Defines the periodicity of buffer flushes in **milliseconds**. | `number` | `10000` | **NO** |
| timeout | Defines the timeout. | `number` | `2000` | **NO** |
| tags | Defines the global tags. | `object` | `{}` | **NO** |
| aggregations | Defines the global aggregations. | `object` | `[]` | **NO** |
| aggregationFrequency | Defines the global aggregation frequency. | `number` | `10` | **NO** |
### Methods
#### counter, gauge, timer
These methods receive a metric name and a metric value as arguments and send a counter/gauge/timer metric.
If the options parameter is omitted, the default values are used.
**These methods will add metrics to a queue that will be flushed using the interval defined on flushInterval.**
```javascript
statful.counter('myCounter', 1, {agg: ['sum']});
statful.gauge('myGauge', 10, { tags: { host: 'localhost' } });
statful.timer('myCounter', 200, {namespace: 'sandbox'});
```
#### sendMetric
This method receive a metric type, metric name and a metric value as arguments and send a counter/gauge/timer metric.
If the options parameter is omitted, the default values are used.
**This method will send metrics to the server without being added to the queue.**
```javascript
statful.sendMetric('counter', 'myCounter', 1, {agg: ['sum']});
```
Read the methods options reference bellow to get more information about the default values.
| Option | Description | Type | Default for Counter | Default for Gauge | Default for Timer |
|:---|:---|:---|:---|:---|:---|
| agg | Defines the aggregations to be executed. These aggregations are merged with the ones configured globally, including method defaults.
**Valid Aggregations:** `avg, count, sum, first, last, p90, p95, p99, min, max` | `array` | `['sum', 'count']` | `[last]` | `['avg', 'p90', 'count']` |
| aggFreq | Defines the aggregation frequency in **seconds**. It overrides the global aggregation frequency configuration.
**Valid Aggregation Frequencies:** `10, 30, 60, 120, 180, 300` | `number` | `10` | `10` | `10` |
| sampleRate | Defines the rate sampling. It overrides the global namespace configuration. | `number` | `100` | `100` | `100` |
| namespace | Defines the namespace of the metric. It overrides the global namespace configuration. | `string` | `web` | `web` | `web` |
| tags | Defines the tags of the metric. These tags are merged with the ones configured globally, including method defaults. | `object` | `{}` | `{}` | `{ unit: 'ms' }` |
### Plugins
* [statful-browser-plugin](https://github.com/statful/statful-browser-plugin) - add browser tags
### User Timing
Support for the [user-timing](http://www.w3.org/TR/user-timing/) specification is available.
You can check the current compatibility table [here](https://caniuse.com/#feat=user-timing).
#### Performance Mark
```
statful.registerMark('mark_start');
statful.registerMark('mark_end');
```
#### Performance Measure sent to Statful as a Timer
```
// Measure and Timer between two marks
statful.registerMark('mark_start');
statful.registerMark('mark_end');
var options = {
startMark: 'mark_start',
endMark: 'mark_end'
tags: {mark: my_tag}
}
statful.registerMeasure('measure_name', 'metric_name' options);
```
```
// Measure and Timer from the navigationStart event until the current time
var options = {
tags: {mark: my_tag}
}
statful.registerMeasure('measure_name', 'metric_name' options);
```
You can omit both start and end mark names:
* if startMark is missing it will be measured from the navigationStart event
* if endMark is missing it will be measured until the current high precision time
## Development
### Installation
```bash
$ npm install
```
### Tests
```bash
$ npm test
```
### Contribute
Follow the standard *Fork and Pull Request* workflow and:
* Add tests for new feats
* Make sure the test suite passes
* Update or add documentation accordingly
## Authors
[Mindera - Software Craft](https://github.com/Mindera)
## License
Statful Javascript Client is available under the MIT license. See the [LICENSE](https://raw.githubusercontent.com/statful/statful-client-javascript/master/LICENSE) file for more information.