Overview

The Exception Logger Plugin API enables developers to create integration to other error or bug tracking software. The platform has built-in logging but it is limited in features. We provide a way to integrate exception events generated by other plugins in the system to external software systems specialised in error or bug tracking. This article aims to provide detailed information on the APIs available for Exception Logger Plugins and how to build one.

Starting a Node.js Exception Logger Plugin Project

To easily create a plugin project scaffolding for Exception Logger plugins, Reekoh has provided a generator tool which can be used like:

cd path/to/your/project-folder

yo reekoh-node:exception-logger

Building the Plugin

The file named app.js is where everything starts. To use the Exception Logger Plugin API, one starts by creating an Exception Logger instance as seen on the scaffolding's app.js file.

app.js

'use strict'

const reekoh = require('reekoh')
const plugin = new reekoh.plugins.ExceptionLogger()

plugin is now an instance of an Exception Logger with the necessary properties, methods, and events for creating an Exception Logger plugin. Details of the Exception Logger instance' properties, methods and events are specified in the following sections.

Properties

Specified below are the properties of an Exception Logger which are injected for use in your plugin.

• config {object} - The custom plugin configuration values as requested from and specified by the end user. For more about plugin configurations, please see the Packaging & Submission section.

Events

Specified below are the events that an Exception Logger is able to emit based upon operations that are happening on the platform pipelines.

'ready'

This event is emitted when the Exception Logger instance has fully initialised. This is usually the event where one listens to and puts the code to initialise a connection to the external error or bug tracking software.

Sample Code

let client

plugin.on('ready', () => {
  client = createClient(plugin.config.apiKey)

  client.on('connected', () => {
    plugin.log('Client is now connected to the bug tracking service')
  })
})

 'exception'

This event is emitted when an error event is received from the platform.

Arguments

• err {error} - The error event log as passed from the platform. This is a standard JavaScript Error object.

Sample Code

plugin.on('exception', err => {
  client.log(err)
})

Methods

Specified below are Exception Logger API methods that you can use for your plugin to relay information and initiate operations on the platform.

setState(state)

Invoke this method to set the plugin's state. State can be used to store additional information or metadata for the plugin. It can also be used as cache for any information that needs to be stored temporarily.

Arguments

• state {any} - state to be stored. Can be anything - object, array, string, number etc.

Returns

• Promise - which is fulfilled when the state has been submitted for storage.

Sample Code

let client

plugin.once('ready', () => {
  client = createClient(plugin.config.apiKey)

  client.on('connected', () => {
    plugin.log('Client is now connected to the bug tracking service')
  })

  plugin.setState({
    config: plugin.config,
    otherMetadata: {
      any: 'connected'
    }
  })
})

getState()

Invoke this method to retrieve the contents of the plugin state. 

Returns

• Promise (state {any}) - resolves or returns the contents of the plugin's state.

Sample Code

let client

plugin.on('exception', err => {
  plugin.getState().then(state => {
    console.log(state)
  })
})

log(logData)

Invoke this function to log any information. Can be useful for debugging. Logs are found under the Logs module or in each plugin instance in the Pipeline Studio.

Arguments

• logData {string | object} - The information to be logged.

Returns

• Promise - fulfilled when the log data has been submitted to the platform for recording.

Sample Code

plugin.on('exception', err => {
  plugin.log('Received exception')
  plugin.log(err.message)

  client.logError(err)
})

logException(err)

Invoke this function to log errors/exceptions. Can be useful for debugging. Error/exception logs are found under the Logs module or in each plugin instance in the Pipeline Studio. 

Arguments

• err {error} - The error to be logged.

Returns

• Promise - fulfilled when the error data has been submitted to the platform for recording.

Sample Code

plugin.on('exception', err => {
  client
    .logException(err)
    .catch(err => {
      plugin.logException(err)
    })
})

Reference Implementations

Listed below are some reference implementations of the Exception Logger Plugin API.

• Sentry Exception Logger
• Raygun Exception Logger
• Airbrake Exception Logger

These are just some of the Exception Logger Plugins developed and open-sourced by Reekoh. You may visit our Gitlab Page for more information. Contributions are most welcome.