angular-loggly-mixin

AngularJS module to pass $log calls thru to Loggly

Summary

The purpose of this module is to allow you to use Loggly in your AngularJS module with as little impact to your existing code as possible.

It works by decorating AngularJS' $log service to pass calls through to Loggly. This means if you're already using $log in your app, you simply need to configure a Loggly key, and it's ready to use.

This module provides sensible defaults, but also allows you to configure it to your liking.

Example

angular.module('myModule', ['fv.loggly-mixin'])
  .config($logglyProvider => {
    // replace with your key.  the "sensible default" is an empty string,
    // which I guess is not so sensible.    
    $logglyProvider.logglyKey('00000000-0000-0000-0000-000000000000')
      // this must be called to decorate the $log service.
      // if you just want the connection to Loggly established (to say, use
      // `$loggly.send()` to communicate directly), omit this.
      .decorate();
  })
  .run($log => {
    $log.info('Ready to work!');
    // sends the following to Loggly:
    // {desc: 'Ready to work!'}
  });

Configuration

All configuration options (as defaults) are shown here:

angular.module('myModule', ['fv.loggly-mixin'])
  .config($logglyProvider => {
    $logglyProvider.logglyKey('00000000-0000-0000-0000-000000000000')
      // tracker url
      .logglyUrl('//cloudfront.loggly.com/js/loggly.tracker.js')
      // whether to pass uncaught errors to Loggly
      .allowUncaught(true)
      // whether or not to allow Loggly to trap calls to console.error()
      .sendConsoleErrors(true)
      // message formatting function.  accepts these two parameters
      // and should return an object.  use this to custom-tailor your
      // data.  
      // this function runs in a `null` context.
      .formatter((level, body) => {
        body.desc = body.desc || '(no description)';
        return Object.assign({level}, body);
      })
      // mapping of new method names to original method names.
      // you can define custom "levels" in this manner, or "forward" all
      // calls from one to another.
      // if `$log.debug` doesn't exist or is disabled, `$log.log` will be used.
      // note that this function will not *remove* any existing settings;
      // $log.error() will still be $log.error() unless you override it.
      .levelMapping({
        debug: 'debug',
        log: 'log',
        info: 'info',
        warn: 'warn',
        error: 'error',
        time: 'log'
      })
      // set the level used by the $log.timeEnd() method to 'time'.
      // it should correspond to a key in the level mapping object.
      // see "Timers" section below for more info.
      .timerLevel('time')
      // whether or not to use a domain proxy
      .useDomainProxy(false)
      // add one or more tags for Loggly; one per argument
      .tags();     

    // in addition, a convenience method exists to map a method;
    // this causes `$log.foo()` to call `$log.log()`.  returns $logglyProvider
    // instance.
    $logglyProvider.mapLevel('foo', 'log');

    // finally, you can grab/modify the entire configuration object this way.
    // property `logglyConfig` is data which will be sent to Loggly; feel free
    // to manually add anything else here.
    // property `providerConfig` is used internally and does not get sent to 
    // Loggly.
    console.dir($logglyProvider.config);

    // call this when finished to decorate the service.
    $logglyProvider.decorate();
  })
  .run($log => {
    // you can also pull the config at runtime
    console.dir($log.config);

    // or send something directly to Loggly
    $log.send({
      foo: 'bar'
    });
  });

String Formatting

If you don't have the luxury of ES2015 template strings, you can use the logging methods in a manner akin to console.log():

$log.info('The %s brown fox jumped over the %s dog', 'quick', 'lazy');

Timers

Since $log has no timing functionality, and it's often useful to send timer information to Loggly, $log will now have two more functions:

$log.timer([label])

Starts a timer with the given {string} label, or label __default__ if omitted.

Returns undefined.

$log.timerEnd([label], [msg], [...data])

Ends the timer for {string} label (using __default__ if omitted), with an optional description {string} msg and optional data {*} data. Supports formatted strings, as noted above.

Sends a message to Loggly of the following format, where {number} ms is elapsed time in milliseconds:

const msg = {
  level: 'time',
  label: label,  
  ms: ms,
  desc: desc,
  data: data
}

If you've used $logglyProvider.timerLevel() to set a different level value, it will be used instead of time.

Returns undefined.

$loggly Service

A $loggly service is available, however, it's mostly for internal usage. $loggly's' main responsibility is to use the configuration as defined in $logglyProvider to initiate communcation with Loggly.

The following members may be of use:

send(data)

Sends {*} data directly to Loggly.

Returns undefined.

config

An Object representation of the configuration as set by $logglyProvider is available here. Modifying it at runtime is unsupported at the time of this writing.

Events

Events are emitted (not broadcast) on $rootScope.

• fv.loggly-mixin:ready: Once the Loggly tracker is "ready", this event is emitted.

• fv.loggly-mixin:timer-started: When a timer has been started via $log.timer(), this event is emitted with the label and a timestamp (from the epoch).

• fv.loggly-mixin:timer-stopped: When a timer has ended via $log.timerEnd(), this event is emitted with an object having the label and a ms field indicating elapsed time.

Installation

npm

$ npm install angular angular-loggly-mixin

This package requires AngularJS 1.2.0 or higher as a peer dependency. AngularJS 2 is not supported at this time.

To use with your favorite bundling tool:

const angular = require('angular');

angular.module('myModule', [require('angular-loggly-mixin')])
  .config($logglyProvider => {
    $logglyProvider.logglyKey('your-key').decorate();  
  });

Bower

$ bower install angular https://npmcdn.com/angular-loggly-mixin/bower.zip

PRO TIP: Don't use Bower.

Author

Christopher Hiller

License

© 2015 FocusVision Worldwide. Licensed Apache-2.0.