statful-client-javascript

Statful client for Javascript. This client is intended to gather metrics and send them to Statful.

Table of Contents

• Supported Versions
• Installation
• Quick Start
• Reference
• Authors
• 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:

    <script type="text/javascript" src="node_modules/statful-client-javascript/dist/statful.umd.min.js"></script>

    <script>    
        // Init statful       
        statful.initialize({
            dryrun: false,
            debug: false,
            app: 'exampleApp',          
            flushInterval: 5000
        });

        // Send a metric
        statful.counter('page_load');
    </script>

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.

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.

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 - add browser tags

User Timing

Support for the user-timing specification is available. You can check the current compatibility table here.

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

$ npm install

Tests

$ 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

License

Statful Javascript Client is available under the MIT license. See the LICENSE file for more information.