laaso v0.2.1

Laaso-NodeJS

Take control of your logs

NodeJS library for Laaso. The rest of this document assumes you know what Laaso is.

Table of Contents:

• Introduction
• Getting Started
• Logging Methods - Console - ExpressJS Middleware - Custom

Introduction

Laaso-NodeJS requires a valid account and app on a Laaso server. You can get an account for the official Laaso instance here. Laaso is currently in private Alpha. To get an account on the official server, please contact Julia.

Using this you can log to Laaso using websockets in any way you like. Some default transports are included and making your own is very easy, if needed.

Should a log attempt fail, it will be attempted again after 30 seconds.

Getting Started

To get started, you must initialize a Logger using your API key and any options you like, listed below:

const Logger = require('laaso').Logger;

// Default Options
new Logger('YOUR TOKEN GOES HERE');

// Custom Options
new Logger({
    token: 'YOUR TOKEN GOES HERE',
    url: 'https://www.laaso.app/'
    // Any other options here
});

Logger Options

token string - (required) Your app's API token. No default

url string - The URL of the Laaso server to use. If you're using a 3rd-party or self-hosted instance, you should set this to their root page. Defaults to 'https://www.laaso.app/'

defaultLevel string - If not otherwise set, log messages sent will use this as their level. If undefined, Laaso-NodeJS will throw an error on logs with undefined levels. Defaults to undefined

defaultEvent string - If not otherwise set, log messages sent will use this as their event name. If undefined, Laaso-NodeJS will throw an error on logs with undefined event names. Defaults to undefined

localLevels array\<string> - Array of levels to keep local and not send to the Laaso server. Useful to keep debug and trace logs from polluting your logs. Defaults to undefined

Logging Methods

Console

Acts as a middleman to console.log or console.error depending on the level used. If this is constructed before a Logger, options passed will be used to attempt to initialize one. Because of this, all options accepted by the Logger class will also be accepted by this.

Usage

// This assumes you've initialized a Logger like shown in Getting Started.
const Console = require('laaso').Console;

// Default Options
let logger = new Console();

// Custom Options
let logger = new Console({
    fancy: true
    // Any other options here
});

logger.info('your log message here.');
logger.error('Oh no, an error!');

Console options

eventName string - Event name to use for console output events. Defaults to "console_output"

fancy boolean - If true, will colorize and format console output. Requires colors. Install using npm i colors --save. Defaults to false

detached boolean - If true, will initialize without a Logger and act as a normal console logger agnostic of the Laaso service. This is *Defaults to false

errorLevels array\<string> - List of log levels to consider errors. This changes wether they are output to stderr or stdout, and their coloring in fancy mode. Defaults to ['error','warn','fatal']

levels array\<string> - List of custom log levels to create functions for. Note that the first is used as the default for log(). Defaults to ['info', 'debug', 'trace', 'warn', 'error']

Express Middleware

Provides middleware to automatically log page views and errors, with customizeable user privacy settings. Like the console logger, if this is constructed before a Logger, options passed will be used to attempt to initialize one. Because of this, all options accepted by the Logger class will also be accepted by this.

Usage

// This assumes you've initialized a Logger like shown in Getting Started.
const Middleware = require('laaso').Middleware;
const express = require('express');

const app = express();

// Default Options
new Middleware();

// Custom Options
new Middleware({
    viewName: 'page_view',
    exclude: {
        ip: true,
        useragent: false
    }
    // Any other options here
});

// Initialize the handlers
app.use(Middleware.requestHandler());
app.use(Middleware.errorHandler());

Express options

viewName string - Event name for page views. Defaults to "page_view"

viewLevel string - Level for page views. Defaults to "info"

errorName, errorLevel - The same as above, except these are used on errors. Default to "express_error" and "error", respectively

exclude object - User-identifying information to exclude or include. Options reliant on other middleware will have no effect if not available. Default:

{
    ip: true, // IP address of the requester
    sessionid: false, // Session ID provided by express-session
    user: false, // User ID and name, or email provided by passport
    useragent: false // User Agent information provided by express-useragent, or the raw string otherwise
}

Custom Logging Methods

Creating custom logging methods is fairly straightforward. You will be using the Logger class directly and will have total control over data sent.

Keep in mind, all log messages must be JSON formatted, and unsupported websocket messages can result in the server terminating the session.

Usage

const Logger = require('laaso').Logger;

let logger = new Logger('YOUR TOKEN HERE');

// To send logs to Laaso, use this function
logger.log('level', 'event', {message:'Now you\'re logging in JSON!'});

logger.log('warn', 'another_event', {limit: 'your imagination'});