statful-client-javascript

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.