1. module node-statsd
   1. function node-statsd (host, port, prefix, suffix, globalize, cacheDns, mock, global_tags)
   2. function node-statsd.StatsD (host, port, prefix, suffix, globalize, cacheDns, mock, global_tags)
   3. object node-statsd.StatsD.prototype
2. module node-statsd.StatsD
   1. function node-statsd.StatsD (host, port, prefix, suffix, globalize, cacheDns, mock, global_tags)
3. module node-statsd.StatsD.prototype
   1. function node-statsd.StatsD.prototype.close ()
   2. function node-statsd.StatsD.prototype.decrement (stat, value, sampleRate, tags, callback)
   3. function node-statsd.StatsD.prototype.gauge (stat, value, sampleRate, tags, callback)
   4. function node-statsd.StatsD.prototype.histogram (stat, value, sampleRate, tags, callback)
   5. function node-statsd.StatsD.prototype.increment (stat, value, sampleRate, tags, callback)
   6. function node-statsd.StatsD.prototype.send (stat, value, type, sampleRate, tags, callback)
   7. function node-statsd.StatsD.prototype.sendAll (stat, value, type, sampleRate, tags, callback)
   8. function node-statsd.StatsD.prototype.set (stat, value, sampleRate, tags, callback)
   9. function node-statsd.StatsD.prototype.timing (stat, time, sampleRate, tags, callback)
   10. function node-statsd.StatsD.prototype.unique (stat, value, sampleRate, tags, callback)

module node-statsd

function node-statsd (host, port, prefix, suffix, globalize, cacheDns, mock, global_tags)

• description and source-code

  node-statsd = function (host, port, prefix, suffix, globalize, cacheDns, mock, global_tags) {
    var options = host || {},
           self = this;
  
    if(arguments.length > 1 || typeof(host) === 'string'){
      options = {
        host        : host,
        port        : port,
        prefix      : prefix,
        suffix      : suffix,
        globalize   : globalize,
        cacheDns    : cacheDns,
        mock        : mock === true,
        global_tags : global_tags
      };
    }
  
    this.host        = options.host || 'localhost';
    this.port        = options.port || 8125;
    this.prefix      = options.prefix || '';
    this.suffix      = options.suffix || '';
    this.socket      = dgram.createSocket('udp4');
    this.mock        = options.mock;
    this.global_tags = options.global_tags || [];
  
    if(options.cacheDns === true){
      dns.lookup(options.host, function(err, address, family){
        if(err == null){
          self.host = address;
        }
      });
    }
  
    if(options.globalize){
      global.statsd = this;
    }
  }

• example usage

  n/a

function node-statsd.StatsD (host, port, prefix, suffix, globalize, cacheDns, mock, global_tags)

• description and source-code

  StatsD = function (host, port, prefix, suffix, globalize, cacheDns, mock, global_tags) {
    var options = host || {},
           self = this;
  
    if(arguments.length > 1 || typeof(host) === 'string'){
      options = {
        host        : host,
        port        : port,
        prefix      : prefix,
        suffix      : suffix,
        globalize   : globalize,
        cacheDns    : cacheDns,
        mock        : mock === true,
        global_tags : global_tags
      };
    }
  
    this.host        = options.host || 'localhost';
    this.port        = options.port || 8125;
    this.prefix      = options.prefix || '';
    this.suffix      = options.suffix || '';
    this.socket      = dgram.createSocket('udp4');
    this.mock        = options.mock;
    this.global_tags = options.global_tags || [];
  
    if(options.cacheDns === true){
      dns.lookup(options.host, function(err, address, family){
        if(err == null){
          self.host = address;
        }
      });
    }
  
    if(options.globalize){
      global.statsd = this;
    }
  }

• example usage

  n/a

module node-statsd.StatsD

function node-statsd.StatsD (host, port, prefix, suffix, globalize, cacheDns, mock, global_tags)

• description and source-code

  StatsD = function (host, port, prefix, suffix, globalize, cacheDns, mock, global_tags) {
    var options = host || {},
           self = this;
  
    if(arguments.length > 1 || typeof(host) === 'string'){
      options = {
        host        : host,
        port        : port,
        prefix      : prefix,
        suffix      : suffix,
        globalize   : globalize,
        cacheDns    : cacheDns,
        mock        : mock === true,
        global_tags : global_tags
      };
    }
  
    this.host        = options.host || 'localhost';
    this.port        = options.port || 8125;
    this.prefix      = options.prefix || '';
    this.suffix      = options.suffix || '';
    this.socket      = dgram.createSocket('udp4');
    this.mock        = options.mock;
    this.global_tags = options.global_tags || [];
  
    if(options.cacheDns === true){
      dns.lookup(options.host, function(err, address, family){
        if(err == null){
          self.host = address;
        }
      });
    }
  
    if(options.globalize){
      global.statsd = this;
    }
  }

• example usage

  n/a

module node-statsd.StatsD.prototype

function node-statsd.StatsD.prototype.close ()

• description and source-code

  close = function (){
      this.socket.close();
  }

• example usage

  ...
    }
  };
  
  /**
   * Close the underlying socket and stop listening for data on it.
   */
  Client.prototype.close = function(){
      this.socket.close();
  }
  
  exports = module.exports = Client;
  exports.StatsD = Client;
  ...

function node-statsd.StatsD.prototype.decrement (stat, value, sampleRate, tags, callback)

• description and source-code

  decrement = function (stat, value, sampleRate, tags, callback) {
    this.sendAll(stat, -value || -1, 'c', sampleRate, tags, callback);
  }

• example usage

  ...
  // Timing: sends a timing command with the specified milliseconds
  client.timing('response_time', 42);
  
  // Increment: Increments a stat by a value (default is 1)
  client.increment('my_counter');
  
  // Decrement: Decrements a stat by a value (default is -1)
  client.decrement('my_counter');
  
  // Histogram: send data for histogram stat
  client.histogram('my_histogram', 42);
  
  // Gauge: Gauge a stat by a specified amount
  client.gauge('my_gauge', 123.45);
  ...

function node-statsd.StatsD.prototype.gauge (stat, value, sampleRate, tags, callback)

• description and source-code

  gauge = function (stat, value, sampleRate, tags, callback) {
    this.sendAll(stat, value, 'g', sampleRate, tags, callback);
  }

• example usage

  ...
  // Decrement: Decrements a stat by a value (default is -1)
  client.decrement('my_counter');
  
  // Histogram: send data for histogram stat
  client.histogram('my_histogram', 42);
  
  // Gauge: Gauge a stat by a specified amount
  client.gauge('my_gauge', 123.45);
  
  // Set: Counts unique occurrences of a stat (alias of unique)
  client.set('my_unique', 'foobar');
  client.unique('my_unique', 'foobarbaz');
  
  // Incrementing multiple items
  client.increment(['these', 'are', 'different', 'stats']);
  ...

function node-statsd.StatsD.prototype.histogram (stat, value, sampleRate, tags, callback)

• description and source-code

  histogram = function (stat, value, sampleRate, tags, callback) {
    this.sendAll(stat, value, 'h', sampleRate, tags, callback);
  }

• example usage

  ...
  // Increment: Increments a stat by a value (default is 1)
  client.increment('my_counter');
  
  // Decrement: Decrements a stat by a value (default is -1)
  client.decrement('my_counter');
  
  // Histogram: send data for histogram stat
  client.histogram('my_histogram', 42);
  
  // Gauge: Gauge a stat by a specified amount
  client.gauge('my_gauge', 123.45);
  
  // Set: Counts unique occurrences of a stat (alias of unique)
  client.set('my_unique', 'foobar');
  client.unique('my_unique', 'foobarbaz');
  ...

function node-statsd.StatsD.prototype.increment (stat, value, sampleRate, tags, callback)

• description and source-code

  increment = function (stat, value, sampleRate, tags, callback) {
    this.sendAll(stat, value || 1, 'c', sampleRate, tags, callback);
  }

• example usage

  ...
  var StatsD = require('node-statsd'),
      client = new StatsD();
  
  // Timing: sends a timing command with the specified milliseconds
  client.timing('response_time', 42);
  
  // Increment: Increments a stat by a value (default is 1)
  client.increment('my_counter');
  
  // Decrement: Decrements a stat by a value (default is -1)
  client.decrement('my_counter');
  
  // Histogram: send data for histogram stat
  client.histogram('my_histogram', 42);
  ...

function node-statsd.StatsD.prototype.send (stat, value, type, sampleRate, tags, callback)

• description and source-code

  send = function (stat, value, type, sampleRate, tags, callback) {
    var message = this.prefix + stat + this.suffix + ':' + value + '|' + type,
        buf,
        merged_tags = [];
  
    if(sampleRate && sampleRate < 1){
      if(Math.random() < sampleRate){
        message += '|@' + sampleRate;
      } else {
        //don't want to send if we don't meet the sample ratio
        return;
      }
    }
  
    if(tags && Array.isArray(tags)){
      merged_tags = merged_tags.concat(tags);
    }
    if(this.global_tags && Array.isArray(this.global_tags)){
      merged_tags = merged_tags.concat(this.global_tags);
    }
    if(merged_tags.length > 0){
      message += '|#' + merged_tags.join(',');
    }
  
    // Only send this stat if we're not a mock Client.
    if(!this.mock) {
      buf = new Buffer(message);
      this.socket.send(buf, 0, buf.length, this.port, this.host, callback);
    } else {
      if(typeof callback === 'function'){
        callback(null, 0);
      }
    }
  }

• example usage

  ...
      if(completed === stat.length){
        callback(null, sentBytes);
      }
    }
  
    if(Array.isArray(stat)){
      stat.forEach(function(item){
        self.send(item, value, type, sampleRate, tags, onSend);
      });
    } else {
      this.send(stat, value, type, sampleRate, tags, callback);
    }
  };
  
  /**
  ...

function node-statsd.StatsD.prototype.sendAll (stat, value, type, sampleRate, tags, callback)

• description and source-code

  sendAll = function (stat, value, type, sampleRate, tags, callback){
    var completed = 0,
        calledback = false,
        sentBytes = 0,
        self = this;
  
    if(sampleRate && typeof sampleRate !== 'number'){
      callback = tags;
      tags = sampleRate;
      sampleRate = undefined;
    }
  
    if(tags && !Array.isArray(tags)){
      callback = tags;
      tags = undefined;
    }
  
    /**
     * Gets called once for each callback, when all callbacks return we will
     * call back from the function
     * @private
     */
    function onSend(error, bytes){
      completed += 1;
      if(calledback || typeof callback !== 'function'){
        return;
      }
  
      if(error){
        calledback = true;
        return callback(error);
      }
  
      sentBytes += bytes;
      if(completed === stat.length){
        callback(null, sentBytes);
      }
    }
  
    if(Array.isArray(stat)){
      stat.forEach(function(item){
        self.send(item, value, type, sampleRate, tags, onSend);
      });
    } else {
      this.send(stat, value, type, sampleRate, tags, callback);
    }
  }

• example usage

  ...
  * @param stat {String|Array} The stat(s) to send
  * @param time {Number} The time in milliseconds to send
  * @param sampleRate {Number=} The Number of times to sample (0 to 1). Optional.
  * @param tags {Array=} The Array of tags to add to metrics. Optional.
  * @param callback {Function=} Callback when message is done being delivered. Optional.
  */
  Client.prototype.timing = function (stat, time, sampleRate, tags, callback) {
   this.sendAll(stat, time, 'ms', sampleRate, tags, callback);
  };
  
  /**
  * Increments a stat by a specified amount
  * @param stat {String|Array} The stat(s) to send
  * @param value The value to send
  * @param sampleRate {Number=} The Number of times to sample (0 to 1). Optional.
  ...

function node-statsd.StatsD.prototype.set (stat, value, sampleRate, tags, callback)

• description and source-code

  set = function (stat, value, sampleRate, tags, callback) {
    this.sendAll(stat, value, 's', sampleRate, tags, callback);
  }

• example usage

  ...
  // Histogram: send data for histogram stat
  client.histogram('my_histogram', 42);
  
  // Gauge: Gauge a stat by a specified amount
  client.gauge('my_gauge', 123.45);
  
  // Set: Counts unique occurrences of a stat (alias of unique)
  client.set('my_unique', 'foobar');
  client.unique('my_unique', 'foobarbaz');
  
  // Incrementing multiple items
  client.increment(['these', 'are', 'different', 'stats']);
  
  // Sampling, this will sample 25% of the time the StatsD Daemon will compensate for sampling
  client.increment('my_counter', 1, 0.25);
  ...

function node-statsd.StatsD.prototype.timing (stat, time, sampleRate, tags, callback)

• description and source-code

  timing = function (stat, time, sampleRate, tags, callback) {
    this.sendAll(stat, time, 'ms', sampleRate, tags, callback);
  }

• example usage

  ...
  If an array is specified as the `name` parameter each item in that array will be sent along with the specified value.
  
  ```javascript
  var StatsD = require('node-statsd'),
      client = new StatsD();
  
  // Timing: sends a timing command with the specified milliseconds
  client.timing('response_time', 42);
  
  // Increment: Increments a stat by a value (default is 1)
  client.increment('my_counter');
  
  // Decrement: Decrements a stat by a value (default is -1)
  client.decrement('my_counter');
  ...

function node-statsd.StatsD.prototype.unique (stat, value, sampleRate, tags, callback)

• description and source-code

  unique = function (stat, value, sampleRate, tags, callback) {
    this.sendAll(stat, value, 's', sampleRate, tags, callback);
  }

• example usage

  ...
  client.histogram('my_histogram', 42);
  
  // Gauge: Gauge a stat by a specified amount
  client.gauge('my_gauge', 123.45);
  
  // Set: Counts unique occurrences of a stat (alias of unique)
  client.set('my_unique', 'foobar');
  client.unique('my_unique', 'foobarbaz');
  
  // Incrementing multiple items
  client.increment(['these', 'are', 'different', 'stats']);
  
  // Sampling, this will sample 25% of the time the StatsD Daemon will compensate for sampling
  client.increment('my_counter', 1, 0.25);
  ...