Natively Pronounced Mandarin

    @samsystem/logger

    1.2.10 • Public • Published

    Description

    This plugin instantiates and exports an instance of winston.Logger configured to follow samsystems logging conventions for logging to kibana correctly. It also exports a logger factory function that can be used to explicitly pass options for creating winston.Logger instance as opposed to based on environment variables.

    Getting started

    • Clone repo: git clone https://github.com/samsystems/logger
    • Run: npm install

    Env vars example

    Package is designed to run without any necessary setup. Just require('@samsystem/logger') and use in your service. It will log to kibana in beta/production environments and to console otherwise.

    If you need to overwrite default behaviour you can use following env variables.

    1. Disable all output

      LOG_SILENT=true
    2. Set custom transports

      LOG_TRANSPORTS=kibana,console
    3. Change log level

      LOG_LEVEL=info
    4. MongoDB transport custom configuration

      LOG_MONGODB_URI=mongodb://localhost
      LOG_MONGODB_COLLECTION=logs
      LOG_MONGODB_LEVEL=error
    5. File transport custom configuration

      LOG_FILE_FILENAME=output.log
    6. Integrate with the debug Node package

      LOG_USE_DEBUG=1

      (and when invoking logger.debug)

      logger.debug('A useful log message', {
          trace: 'package:class:method',
      });
    7. Splunk transport custom configuration

      LOG_SPLUNK_TOKEN=<token_access_splunk>
      LOG_SPLUNK_URL=<url_to_splunk>

    Variables follow pattern:

    1. General variables LOG_*
    2. Transport specific variables LOGTRANSPORT* Transport specific variables overwrite general variables.

    If you want to create custom logger you can use factory from lib/utils/createLogger.js to create your own logger.

    How to use

    Exported module is an instance of winston.Logger. If silent is false then the returned logger instance will use a instance of winston.transport.Console as the transport. Transports and logging-levels are able to be changed dynamically refer to docs

    Using log-level and silent-mode set by environment variables

    // pre-configured based on process.env.LOG_LEVEL  and process.env.LOG_SILENT
    // defaults to {silent: false, level: 'info'}
    const logger = require('@samsystem/logger');
    
    logger.info('Inserted Customer', { customer: 'theCustomer' });
    // {"customer":"theCustomer","level":"info","message":"Inserted Customer"}
    
    logger.error('Error inserting customer', {
        error: 'the error message',
        customer: 'theCustomer',
    });
    // {"error":"the error message","customer":"theCustomer","level":"error","message":"Error inserting customer"}
    
    logger.warn('Customer not found with email', { email: 'the@email.com' });
    // {"email":"the@email.com","level":"warn","message":"Customer not found with email"}
    
    // LOGGING_LEVEL env variable must be set to debug in order for debug to show
    
    logger.debug('the customer', { customer: 'theCustomer' });
    // {"customer":"theCustomer","level":"debug","message":"the customer"}

    Using createLogger method

    const createLogger = require('@samsystem/logger/lib/utils/createLogger');
    const logger = createLogger({
        // winston.Logger options
    });

    When using ElasticSearch transport

    The ElasticSearch transport allows log data to be sent straight to ES without the need to be parsed by fluentd/logstash allowing for a more robust set of logs to be stored. In order to make it function properly the following environment variables need to be defined:

    1. LOG_ELASTICSEARCH_INDEX This specifies which index to use, as a matter of best practice the index should be named after the application
    2. LOG_ELASTICSEARCH_HOST The actual ES host to use, if the logger cannot connect to the ES host it will buffer a number of log messages (~5000) in memory and then bulk write them once it can heartbeat ElasticSearch

    logger.tap

    tap is a curried version of the logger, making it well suited for promise chains or functional composition.

    Tap methods:

    • tap
    • tapInfo
    • tapVerbose
    • tapDebug
    • tapWarn
    • tapError
    • tapCritical

    You can call tap directly, and supply the log level you wish to use.

    // tap
    return getUser(username).then(
        logger.tap('debug', `Retrieved user with username: ${username}`),
    );

    Or you can use the convenience methods for each log level.

    // tapInfo
    return getUser(username).then(
        logger.tapInfo(`Retrieved user with username: ${username}`),
    );
    
    // tapVerbose
    return getUser(username).then(
        logger.tapVerbose(`Retrieved user with username: ${username}`),
    );
    
    // tapDebug
    return getUser(username).then(
        logger.tapDebug(`Retrieved user with username: ${username}`),
    );

    logger.tapAndThrow

    tapAndThrow is similar to logger.tap, but instead of returning the logged value, it throws it.

    Tap and Throw methods:

    • tapAndThrow
    • tapAndThrowInfo
    • tapAndThrowVerbose
    • tapAndThrowDebug
    • tapAndThrowWarn
    • tapAndThrowError
    • tapAndThrowCritical

    You can call tapAndThrow directly, and supply the log level you wish to use.

    // tapAndThrow
    return getUser(username)
        .then(logger.tapDebug(`Retrieved user with username: ${username}`))
        .catch(
            logger.tapAndThrow(
                'error',
                `Unexpected error finding user. username: ${username}`,
            ),
        );

    Or you can use the convenience methods for each log level.

    // tapAndThrowCritical
    return getUser(username)
        .then(logger.tapDebug(`Retrieved user with username: ${username}`))
        .catch(
            logger.tapAndThrowCritical(
                `Unexpected error finding user. username: ${username}`,
            ),
        );
    
    // tapAndThrowError
    return getUser(username)
        .then(logger.tapDebug(`Retrieved user with username: ${username}`))
        .catch(
            logger.tapAndThrowError(
                `Unexpected error finding user. username: ${username}`,
            ),
        );
    
    // tapAndThrowWarn
    return getUser(username)
        .then(logger.tapDebug(`Retrieved user with username: ${username}`))
        .catch(
            logger.tapAndThrowWarn(
                `Unexpected error finding user. username: ${username}`,
            ),
        );

    Keywords

    none

    Install

    npm i @samsystem/logger

    DownloadsWeekly Downloads

    227

    Version

    1.2.10

    License

    MIT

    Unpacked Size

    52.6 kB

    Total Files

    33

    Last publish

    Collaborators

    • samsystem