usage-stats

A minimal, offline-friendly Google Analytics Measurement Protocol client for tracking usage statistics in shell and javascript applications.

This is a low-level API client, it doesn't hold any opinion of how usage tracking should be done. If you're looking for a convention which leverages the power and flexibility of Custom Metrics and Dimensions, take a look at app-usage-stats.

Synopsis

Command line

Tracking statistics in shell scripts:

# Track an event: category 'Backup', action 'start'
usage-stats event --tid UA-98765432-1 --ec Backup --ea start

# Perform the backup
cp files/** backup/

# Track an event: category 'Backup', action 'complete'
usage-stats event --tid UA-98765432-1 --ec Backup --ea complete

API

The most trivial example.

const UsageStats = require('usage-stats')
const usageStats = new UsageStats('UA-98765432-1', { an: 'example' })

usageStats.screenView('screen name')
usageStats.event('category', 'action')
usageStats.send()

More realistic usage in a server application:

const UsageStats = require('usage-stats')
const usageStats = new UsageStats('UA-98765432-1', {
  an: 'encode-video',
  av: '1.0.0'
})

// start a new session
usageStats.start()

// user set two options..
usageStats.event('option', 'verbose-level', 'infinite')
usageStats.event('option', 'preset', 'iPod')

try {
  // Begin. Track as a screenView.
  usageStats.screenView('encoding')
  beginEncoding(options)
} catch (err) {
  // Exception tracking
  usageStats.exception(err.message, true)
}

// finished - mark the session as complete
// and send stats (or store if offline).
usageStats.end().send()

Protocol Parameters

See here for the full list of Google Analytics Measurement Protocol parameters.

Sent by default

All parameters are send on demand, beside this list.

Operating System version (sent in the UserAgent)
Client ID (a random UUID, generated once per OS user and stored)
Language (process.env.LANG, if set)
Screen resolution (terminal rows by columns, by default)

CLI Reference

To install the command line client:

$ npm install -g usage-stats

Running the tool with no arguments will print the usage guide:

usage-stats

  A minimal, offline-friendly Google Analytics Measurement Protocol client for
  tracking usage statistics in shell and javascript applications.

Synopsis

  $ usage-stats <command> <command-options>
  $ usage-stats <command> --help

Commands

  screenview   Track a screenview
  event        Track an event
  exception    Track an exception

API Reference

Kind: Exported class

UsageStats ⏏
- new UsageStats(trackingId, [options])
- .dir : string
- .defaults : Map
- .start([sessionParams]) ↩︎
- .end([sessionParams]) ↩︎
- .disable() ↩︎
- .enable() ↩︎
- .event(category, action, [options]) ⇒ Map
- .screenView(name, [options]) ⇒ Map
- .exception([options]) ⇒ Map
- .send([options]) ⇒ Promise
- .debug() ⇒ Promise
- .abort() ↩︎

new UsageStats(trackingId, [options])

Param	Type	Description
trackingId	`string`	Google Analytics tracking ID (required).
[options]	`object`
[options.an]	`string`	App name
[options.av]	`string`	App version
[options.lang]	`string`	Language. Defaults to `process.env.LANG`.
[options.sr]	`string`	Screen resolution. Defaults to `${process.stdout.rows}x${process.stdout.columns}`.
[options.ua]	`string`	User Agent string to use.
[options.dir]	`string`	Path of the directory used for persisting clientID and queue. Defaults to `~/.usage-stats`.
[options.url]	`string`	Defaults to `'https://www.google-analytics.com/batch'`.
[options.debugUrl]	`string`	Defaults to `'https://www.google-analytics.com/debug/collect'`.

Example

const usageStats = new UsageStats('UA-98765432-1', {
  an: 'sick app',
  av: '1.0.0'
})

usageStats.dir : `string`

Cache directory. Defaults to ~/.usage-stats.

Kind: instance property of UsageStats

usageStats.defaults : `Map`

A list of parameters to be to sent with every hit.

Kind: instance property of UsageStats
Example

usageStats.defaults
  .set('cd1', process.version)
  .set('cd2', os.type())
  .set('cd3', os.release())
  .set('cd4', 'api')

usageStats.start([sessionParams]) ↩︎

Starts the session.

Kind: instance method of UsageStats
Chainable

Param	Type	Description
[sessionParams]	`Array.<Map>`	An optional map of paramaters to send with each hit in the sesison.

usageStats.end([sessionParams]) ↩︎

Ends the session.

Kind: instance method of UsageStats
Chainable

Param	Type	Description
[sessionParams]	`Array.<Map>`	An optional map of paramaters to send with the final hit of this sesison.

usageStats.disable() ↩︎

Disable the module. While disabled, all operations are no-ops.

Kind: instance method of UsageStats
Chainable

usageStats.enable() ↩︎

Re-enable the module.

Kind: instance method of UsageStats
Chainable

usageStats.event(category, action, [options]) ⇒ `Map`

Track an event. All event hits are queued until .send() is called.

Kind: instance method of UsageStats

Param	Type	Description
category	`string`	Event category (required).
action	`string`	Event action (required).
[options]	`option`
[options.el]	`string`	Event label
[options.ev]	`string`	Event value
[options.hitParams]	`Array.<map>`	One or more additional params to send with the hit.

usageStats.screenView(name, [options]) ⇒ `Map`

Track a screenview. All screenview hits are queued until .send() is called. Returns the hit instance.

Kind: instance method of UsageStats

Param	Type	Description
name	`string`	Screen name
[options]	`object`
[options.hitParams]	`Array.<map>`	One or more additional params to set on the hit.

usageStats.exception([options]) ⇒ `Map`

Track a exception. All exception hits are queued until .send() is called.

Kind: instance method of UsageStats

Param	Type	Description
[options]	`object`	optional params
[options.exd]	`string`	Error message
[options.exf]	`boolean`	Set true if the exception was fatal
[options.hitParams]	`Array.<map>`	One or more additional params to set on the hit.

usageStats.send([options]) ⇒ `Promise`

Send queued stats using as few requests as possible (typically a single request - a max of 20 events/screenviews may be sent per request). If offline, the stats will be stored and re-tried on next invocation.

Kind: instance method of UsageStats
Fulfil: response[] - array of responses. Each response has data and the original node res.
Reject: Error - Rejects with the first error encountered. The error is a standard node http error with a name of request-fail and a hits property showing what failed to send.

Param	Type
[options]	`object`
[options.timeout]	`number`

usageStats.debug() ⇒ `Promise`

Send any hits (including queued) to the GA validation server, fulfilling with the result.

Kind: instance method of UsageStats
Fulfil: Response[]
Reject: Error - Error instance includes hits.

usageStats.abort() ↩︎

Aborts the in-progress .send() operation, queuing any unsent hits.

Kind: instance method of UsageStats
Chainable

stephenkeep/usage-stats

usage-stats

Synopsis

Command line

API

Protocol Parameters

Sent by default

CLI Reference

API Reference

new UsageStats(trackingId, [options])

usageStats.dir : string

usageStats.defaults : Map

usageStats.start([sessionParams]) ↩︎

usageStats.end([sessionParams]) ↩︎

usageStats.disable() ↩︎

usageStats.enable() ↩︎

usageStats.event(category, action, [options]) ⇒ Map

usageStats.screenView(name, [options]) ⇒ Map

usageStats.exception([options]) ⇒ Map

usageStats.send([options]) ⇒ Promise

usageStats.debug() ⇒ Promise

usageStats.abort() ↩︎

usageStats.dir : `string`

usageStats.defaults : `Map`

usageStats.event(category, action, [options]) ⇒ `Map`

usageStats.screenView(name, [options]) ⇒ `Map`

usageStats.exception([options]) ⇒ `Map`

usageStats.send([options]) ⇒ `Promise`

usageStats.debug() ⇒ `Promise`