devsig-client
v0.2.4
Published
client module for pushing data to the devsig server
Downloads
4
Readme
devsig-client
Client module for pushing data to the devsig server.
Getting Started
Installing
Using npm:
npm i devsig-client
Using yarn:
yarn add devsig-client
Importing
Using require:
const { Client } = require('devsig-client');
Using import:
import { Client } from 'devsig-client';
Initializing
Initialize one instance per user. Supply the user's email and the client token to the constructor.
const client = new Client('[email protected]', 'client-token');
After this you can start sending the user's metrics to the server.
client.send('network.download_speed', 12.95);
Getting the client token
Reach out to the LearnTech team to generate a client token.
API
devsig-client
implements a fluent interface, meaning you call chain method calls together.
client.send('network.download_speed', 12.95).send('network.upload_speed', 5.94);
Note that chaining method calls together has exactly the same effect as calling those methods one at a time. This snippet:
client
.period('minute')
.send('network.download_speed', 12.95)
.date('2019-09-25T13:30:00.000Z')
.period('hour')
.send('network.upload_speed', 5.94);
can be rewritten as
client.period('minute');
client.send('network.download_speed', 12.95);
client.date('2019-09-25T13:30:00.000Z');
client.period('hour');
client.send('network.upload_speed', 5.94);
send
send(metric: string, value: number, cb?: Callback): Client
This method sends a record of a metric to the server.
parameters
metric
This is astring
parameter that represents the name of the metric being measured.value
This is anumber
parameter that represents the value of the metric being measured.cb
This is an optionalCallback
parameter for passing in custom user logic to run after the record has been sent to the server.
export type Callback = (error?: Error, result?: Result) => {}
export type Result = {
data?: any,
error?: any
}
It represents a function that accepts an Error
object (if the operation fails to send the record to the server) and a Result
object (if the operation successfully sends the record to the server). Both objects cannot be present simultaneously; if one is present then the other is undefined
.
Note that result
is what is gotten back from the server, and will contain the following fields:
- data: if the record was successfully saved in the database
- error: if the record could not be saved in the database (probably because the client isn't authorized to do that)
example
client
.send('network.download_speed', 12.95)
.send('network.upload_speed', 5.94, (error, result) => {
if (result) {
console.log('result from the server is:');
console.log(result);
}
});
date
date(date?: Date | string): Client
This method sets the date to be attached to a record. Each record has a date
field. By default this is the actual date the record was created in the database. However, sometimes you may want to back-date a record. A use case is during weekly uploads of records on a Friday. Even though all records will be created at that date (as seen in the createTime
field), you may want to back-date some records to reflect the actual time they were generated.
parameters
- date
This is aDate
orstring
parameter that represents the date to be assigned to records.
example
client
.date('2019-09-25T13:30:00.000Z')
.send('network.download_speed', 12.95)
.date(new Date(2019, 8, 25, 14, 30, 0, 0))
.send('network.upload_speed', 5.94);
period
period(period?: Period): Client
A period is a time duration within which all records of a metric for a user have the same value
(and date
). Supported periods are:
export type Period = 'minute' | 'hour' | 'day' | 'month' | 'year';
For example, to set the values of all network.download_speed
records for the day to 20
:
client
.period('day')
.send('network.download_speed', 20);
To set the values of all network.download_speed
records for a specific date to 20
, supply the date using the date
function:
client
.date('2019-09-25T13:30:00.000Z')
.period('day')
.send('network.download_speed', 20);
Why should you use this? There are metrics you want to record once a day for a user. Imagine a metric like calls_per_day
which represents the number of calls a user has per day. You don't want to store multiple records of this metric for a user in a day. That's what the period
function does. The first time the record is sent to the server within that day, that record is saved to the database. Every other time that record is sent within that day, no new record is saved to the database. Instead, the existing record in the database is updated with the value
(and date
) of the incoming record.
client
.period('day')
.send('calls_per_day', 20); // first call creates a new record in the database
client
.period('day')
.send('calls_per_day', 30); // next call updates the record from '20' to '30'
The same logic applies for other periods: minute
, hour
, month
, year
.
// although this loop is infinite only 1 record of 'calls_per_day'
// for the current user will be created every hour
let calls = 1;
while (true) {
client
.period('hour')
.send('calls_per_day', calls++);
}
reset
reset(): Client
Each instance of the devsig client is mutable; calling functions like date
and period
changes the internal state of that instance. To return the instance back to its default state, call the reset
function.
client
.send('calls_per_day', 10); // creates a new record of 'calls_per_day' in the database
.send('calls_per_day', 20); // creates a new record of 'calls_per_day' in the database
.period('minute') // modifies state
.send('calls_per_day', 30); // updates all records of 'calls_per_day' created in this minute
.reset() // returns state back to normal
.send('calls_per_day', 40); // creates a new record of 'calls_per_day' in the database