Kansas Metrics

Metrics utilities for the Kansas package

Install

Install the module using NPM:

npm install kansas-metrics --save

Table of Contents

1. Overview
2. API
   1. Configuration Methods
      1. setup() Setup Kansas Metrics
      2. options() Configure Kansas Metrics
   2. Query Methods
      1. kansasMetrics() The base constructor
      2. user() Filter by Owner Id
      3. token() Filter by Token Id
      4. from() and to() date filters
   3. Query Methods
      1. Fetching the results
      2. The Results Data Object

Overview

Kansas Metrics (KM) needs to be setup once per your application boot, the setup process is very easy the only thing you need to do is Inject the Kansas instance to KM:

var kansasMetrics = require('kansas-metrics');
 
// Inject once the current working Kansas instance.
kansasMetrics.setup(kansas);

Kansas Metrics needs to be initialized for each new query you want to perform:

var query = kansasMetrics();

You may then add query filters on the returned object:

var kansasMetrics = require('kansas-metrics');
 
kansasMetrics()
    .user('unique uid')
    .from(fromDt)
    .to(toDt)
    .fetch()
        .then(function(results) {})
        .catch(function(err) {});

API

Configuration Methods

setup() Setup Kansas Metrics

Kansas Metrics needs only be setup once using the setup(kansas) method. You have to pass the Kansas instance that your application is currently using and Kansas Metrics will auto-configure based on Kansas settings.

kansasMetrics.setup(kansas)

• kansas Kansas The instance of Kansas you are using.

Returns undefined Nothing.

options() Configure Kansas Metrics

kansasMetrics.options(options)

• options Object A set of options

Returns undefined Nothing.

Available options:

• concurrency {number} How many concurrent Redis operations KM should run, default is 10.

[⬆]

Query Methods

kansasMetrics() The Base Constructor

To start any type of query you need to invoke the Kansas Metrics Constructor which is the function that you get once you require the KM package. Typically the Ctor does not need any arguments but for edge cases you may pass it a Kansas Instance to override the global settings and use the ones defined in the injected Kansas instance.

kansasMetrics(optKansas)

• optKansas Kansas= Optionally pass a Kansas Instance to override global configuration.

Returns self Chainable.

[⬆]

user() Filter by Owner Id

Query by owning user id.

kansasMetrics().user(query)

• query string|Array Owner id or array of owner ids.

Returns self Chainable.

As a single string:

kansasMetrics()
    .user('unique uid')
    .fetch()
        .then(function(results) {});

You can add multiple user() queries:

kansasMetrics()
    .user('unique uid')
    .user('another unique uid')
    .user('one more unique uid')
    .fetch()
        .then(function(results) {});

Or as a single array:

kansasMetrics()
    .user(['unique uid', 'another unique uid', 'one more unique uid'])
    .fetch()
        .then(function(results) {});

[⬆]

token() Filter by Token Id

Query by token id.

kansasMetrics().token(query)

• query string|Array Token id or array of token ids.

Returns self Chainable.

As a single string:

kansasMetrics()
    .token('token id')
    .fetch()
        .then(function(results) {});

You can add multiple token() queries:

kansasMetrics()
    .token('token id')
    .token('another token id')
    .token('one more token id')
    .fetch()
        .then(function(results) {});

Or as a single array:

kansasMetrics()
    .token(['token id', 'another token id', 'one more token id'])
    .fetch()
        .then(function(results) {});

[⬆]

from() and to() date filters

Filter from and to a date.

kansasMetrics().from(query)

kansasMetrics().to(query)

• query string|Date Date

Returns self Chainable.

Both the from() and to() methods accept any string that can evaluate to a date using the native Javascript Date() method. Since Kansas periods are monthly, any date passed will get rounded to the month it belongs before the query is executed, e.g,

For from() methods:

• 23 Sep 2014 --> 01 Sep 2014, will query from and including the month of September 2014.

For to() methods:

• 23 Sep 2014 --> 30 Sep 2014, will query up to and including the month of September 2014.

You may use each one of the methods on their own or both.

As a string:

kansasMetrics()
    .from('01-01-2014')
    .to('05-01-2014')
    .fetch()
        .then(function(results) {});

As a native Date object:

var dt = new Date('01-01-2014');
 
kansasMetrics()
    .from(dt)
    .fetch()
        .then(function(results) {});

[⬆]

Execution Methods

fetch() Execute the Query

Executes the query, returns a Promise.

kansasMetrics().fetch()

Returns Promise(Array.<Object>) A Promise with the results, Kansas Metrics uses the Bluebird implementation.

If no query methods are used then all usage records will be fetched, handle with care.

kansasMetrics()
    .fetch()
        .then(function(results) {
            results.forEach(function(result) {
                console.log(result);
            });
        })
        .catch(function(err) {
            console.error('Error:', err);
        });

[⬆]

The results data objects

All results produced by Kansas Metrics are Arrays of Objects. Each Object has the following schema:

• token {string} A 32char unique token.
• ownerId {string} A string uniquely identifying the owner of the token.
• policyName {string} The name of the policy the token belongs to.
• policyLimit {number} The limit enforced by the policy if it's of type Limit.
• isPolicyCount {boolean} Indicates if the policy is of type Count.
• month {number} The month this usage item refers to (1-12).
• year {number} The year this usage item refers to.
• date {string} An ISO 8601 formated date.
• period {string} Stubbed to month for now.
• usage {number} The units consumed or remaining depending of the Policy type (count / limit).

[⬆]

Release History

• v0.0.3, 12 Nov 2014
  • Added defenses for bogus token keys, robustness++.
• v0.0.1, 01 Nov 2014
  • Big Bang

License

Copyright (c) 2014 Thanasis Polychronakis. Licensed under the MIT license.