flexible-logging-service v1.0.0

Flexible Logger

A simple logging package for nodejs. Oriented towards flexibility, supports logging to an ElasticSearch instance by default through the ElasticSearchDriver class.

Support for GeoLite IP lookup is immediate, you just need to extend the IpLogEntry class.

Support for access logging of an express web server is out-of-the-box through the AccessLogEntry class, which will extract all the useful information from the Express Request object.

Support for additional logging facilities is easily accomplished by extending the interface LoggerDriver which has just one method: write(LogEntry).

Additionally, to limit the rate of network requests, the indexing can be bulked by moving it to an additional node.js instance using the UDP driver. Set up the LogUdpServer on a different instance running inside your network and use the UdpDriver to send the logs to it.

Usage:

import FlexibleLogger from 'flexible-logger';
...

/* Instanciated asynchronously */

const Logger = await FlexibleLogger.with(new ElasticSearchDriver({
    setup: { ... }, // ElasticSearch Configuration
    indexPattern: 'my-index' // Index where documents will be inserted
    }), 
    'path/to/geolite2-city.mmdb' // Path to the GeoLite2 City database
);

/* or */

FlexibleLogger.with(...).then(Logger => {
    ...
});

/* Instanciated synchronously
 * Might be a better choice especially if you need a global instance that
 * gets initialized once and gets called in your code like a Singleton
 */

const Logger = FlexibleLogger.withSync( ... );

Logging...

Logger.log(new AccessLogEntry(
    req, // the Express Request object
    'access-log' // context info
));

/* You can use one of the builtin LogEntries or 
 * you can subclass one of them to add custom data 
 */

class MyLogEntry extends IpLogEntry {
    anotherProperty: any;
    
    constructor(context: string, ip: string, myCustomProperty: number) {
        // if you extend IpLogEntry class and you specified a GeoLite db, 
        // the ip will be parsed into geo location data
        super(context, ip, "MyLogEntry");
        
        // the body property is the one that will be sent to the logging service
        this.body.my_property = myCustomProperty;
        
        // or you can add new a new one and write a new driver to handle it
        this.anotherProperty = "Cheese Cake";
    }
}

A simple access-log middleware for Express servers

app.use((req, res, next) => {
    Logger.log(new AccessLogEntry(req, "access-log"));
    next();
});

Usage with the UDP Driver

const Logger = FlexibleLogger.withSync(
    new UdpDriver('localhost', 12345)
);

which requires a server listening on the given UDP port

const Server = new LogUdpServer(
    new ElasticSearchDriver({ ... }), 
    {
        port: 1234,
        address: 'localhost'
    }
);

Server.bind();
Server.poll();

The UDP server can be configured with the following options

export interface ServerConfig {
    /**
     * Port to bind the server on
     */
    port: number;
    /**
     * Address to bind the server on. Defaults to 0.0.0.0 (any)
     */
    address?: string;
    /**
     * If an error occurs, bind again the port after a timeout. Default is true
     */
    retryOnError?: boolean;
    /**
     * Timeout in ms to wait before retrying binding the port. Default is 10000
     */
    bindRetryTimeout?: number;
    /**
     * Rate in ms at which to flush the queue and send it to the service. Default is 20000
     */
    queuePollRate?: number;
    /**
     * Minimum amount of entries before the messages are sent to the service. Default is 1
     */
    logEntriesTreshold?: number;
    /**
     * If set to true, messages queue will always be flushed even if an error prevented them
     * from being sent to the service. Default is true
     */
    alwaysFlush?: boolean;
}