Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/acquia/ember-logging-service

A generic ember logging service
https://github.com/acquia/ember-logging-service

Last synced: 3 months ago
JSON representation

A generic ember logging service

Awesome Lists containing this project

README 

        
# ember-logging-service [![Build Status](https://travis-ci.com/acquia/ember-logging-service.svg?token=xpbhY9xz7Z9aqH5aUfgP&branch=master)](https://travis-ci.com/acquia/ember-logging-service)



This addon provides a general and extensible logging service that can be used

throughout your application.  This addon by itself will provide a basic logging

service that can be used to trigger log events as well as register consumers to

listen for events.



Example consumers include:

* https://github.com/acquia/ember-logging-amplitude/ for Amplitude integration

* https://github.com/acquia/ember-logging-bugsnag/ for Bugsnag integration

* https://github.com/acquia/ember-logging-flash-messages/ for Flash Messages integration



# Installation

The addon can be installed using standard ember-cli syntax:

```

ember install ember-logging-service

```



# Basic usage

The core functionality of ember-logging-service is a logging service that can

be injected using Ember's standard dependency injection functionality.



```

import Ember from 'ember';



export default Ember.Component.extend({

  logger: Ember.inject.service(),



  trackSomethingAwesome() {

    this.get('logger').info('Something awesome happened!!!', { who: 'Kermit' });

  }

});

```



# Concepts

## Triggering events

The logging service categorizes each event with a 'level' and a 'tag'.  The level

is meant as an indicator of the severity.  Currently the supported levels are:

info, warning, and error.  These values are defined on the "levels" property

of the logger service.  A tag is meant as a general user-defined categorization

of a class of events.



For example, events tracking user behavior could all be tagged with 'user' such

that a user login would be triggered with the level of "info" and the tag of "user".

To trigger this type of event:



`this.get('logger').info('user', 'Log in');`



Similarly, navigation events could be tracked as:

`this.get('logger').info('navigation', 'About')`



Helper functions are provided for each level for logging events.  Each function

can optionally accept additional data to be sent along with the event. 

```

let logger = this.get('service');

logger.info('user', 'Log out');

logger.warning('user', 'Cancelled save');

logger.error('error', 'API authorization error', { status: 403, foo: bar });

```



## Event consumers

Consumers can register with the logging service to listen for any events matching

the a specific combination of event level and event tags.  For example, one

output may only care about error events and handle them accordingly by sending

to Bugsnag or writing to a log.  Other tracking systems may care about user

interaction events for UX analyzation.



A consumer can be registered with the logger by minimally providing an id, a

callback for events, a list of levels, and a list of tags.



For example:

`this.get('logger').registerConsumer('muppets', happyFunc, 'info', ['sesame', 'muppets', monsters']);`



Typically consumers are registered with application instance initializers within

a consumer addon.



When an event is sent to the logger service that matches the level and tag combination

for a consumer, the consumer's callback function is triggered with a structured

event and the context of the application at the time of the event (more below).



The event is structured with the following data:

* name: the name of the event trigger

* type: the tag associated with the event

* level: the severity level (info, warn, error)

* metadata: any additional data passed when the event was triggered



The context object is structured with the following keys:

* application: Any application-specific context provided

* user: Any user-specific context provided



## Application/User Context

The logger service can automatically include application and user context along

with each event.  This is the second parameter sent to the consumer callback

mentioned above.  Because this information is specific to an application, it is

generated by the application that consumes the logger service.  The logger service

allows the registration of one or more application context callbacks and user

context callbacks.  These callbacks are executed with each event to generate

a POJO of contextual information that can be used to provide additional context

to consumers.  For example, it may be useful to provide customer API keys or

the current route within the application to give context to a navigation or 

error event.



Both types of callbacks do not accept any parameters and return a POJO of custom

information.



After installing the ember-logging-service addon an application instance initializer

is automatically created at `app/instance-initializers/register-logging-context.js`



This provides a sample registration of empty application and user context

callbacks.  This can be used as a guide to provide your own data into the

placeholder callbacks or to register your own service functions to provide the

data.



## Automatic Error Monitoring 

When error handling is turned on, the logging service will automatically monitor

any uncaught Ember or RSVP errors and send them as error level events.



# Configuration

To enable ember-logging-service for an environment, include the following

configuration information in your `config/environment.js`:



```

ENV['ember-logging-service'] {

  enabled: true

}

```



To enable ember-logging-service to handle basic error monitoring for an 

environment then include this additional property:



```

ENV['ember-logging-service'] {

  enabled: true,

  errorsEnabled: true

}

```



## Constants

It can be useful to refer to levels, tags, and events as variables rather than

hard-coding the values in your code.  The service already provides the ability

to refer to tags and levels by variable names rather than hard-coded strings.



For example:

* `this.get('logger.levels.info')`

* `this.get('logger.levels.warn')`

* `this.get('logger.levels.error')`



If the logger is tracking the following tags: navigation, interaction, error:

* `this.get('logger.tags.navigation')`

* `this.get('logger.tags.interaction')`

* `this.get('logger.tags.error')`



Consider an example where you are tracking a user interaction event for a 

usability tracking system as "Menu navigation", but for purposes of reporting, 

you UX department now requires you to track the event as 

"Interaction - navigation - menu".  If you had been tracking this event in

multiple places as `this.get('logger').info(this.get('logger.tags.interaction'), 'Menu navigation')`

you would need to update this event name in multiple places.



You could handle this in a couple of ways:

* Maintain a list of strings on paper :(

* Create a configuration of events in JSON format

* Utilize an Ember service to define constant values



The logger service provides an optional mechanism to help with this.  If an

object of event data is passed in the configuration, the logger will automatically

register all of the tags and add the events into an object for easy reference.



Example configuration:

```

ENV['ember-logging-service'] {

  enabled: true,

  events: {

    navgiation: {

      ABOUT: 'About us',

      HOME: 'Home',

      CONTACT: 'Contact'

    },

    muppets: {

      KERMIT: 'Kermie',

      PIGGY: 'Piggy',

      SWEDISH_CHEF: 'Swedish Chef'

    }

  }

}

```

With the above, all of the events will be available from the logger service

based on their tag:



```

let logger = this.get('logger');

console.log(logger.get('events.navigation.ABOUT')); // About us

console.log(logger.get('events.muppets.KERMIT')); // Kermie

```



This is not required for setting up the logger service and is only provided

as a convenience mechanism.



# Developing for ember-logging-service



## Installation



* `git clone [email protected]:acquia/ember-logging-service.git` this repository

* `cd ember-logging-service`

* `npm install`

* `bower install`



## Running



* `ember serve`

* Visit your app at [http://localhost:4200](http://localhost:4200).



## Running Tests



* `npm test` (Runs `ember try:each` to test your addon against multiple Ember versions)

* `ember test`

* `ember test --server`



## Building



* `ember build`



For more information on using ember-cli, visit [https://ember-cli.com/](https://ember-cli.com/).