Statful client for Javascript applications

gather-metrics, javascript, metrics, performance, statful
npm install statful-client-javascript@2.2.3



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

Build Status devDependency Status install size

Table of Contents

Supported Versions

It supports every browser that has full support for the ECMAScript 5 specification.


npm install --save statful-client-javascript


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>

        // Init statful       
            dryrun: false,
            debug: false,
            app: 'exampleApp',          
            flushInterval: 5000

        // Send a metric


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


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'});


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' }


User Timing

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

Performance Mark


Performance Measure sent to Statful as a Timer

// Measure and Timer between two marks


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



$ npm install


$ npm test


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


Mindera - Software Craft


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