Overview

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

Starting a Node.js Logger Plugin Project

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

cd path/to/your/project-folder

yo reekoh-node:logger

Building the Plugin

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

app.js

'use strict'

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

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

Properties

Specified below are the properties of a 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 information about plugin configurations, please see the Packaging & Submission section.

Events

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

'ready'

This event is emitted when the Logger instance has fully initialized. This is usually the event where one listens to and puts the code to initialize a connection to the external logging software.

Sample Code

let client

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

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

'log'

This event is emitted when a log data is received. 

Arguments

• data {string} - The event log or data as passed from the platform. This can be a JSON String.

Sample Code

plugin.on('log', logData => {
  client.log(JSON.parse(data))
})

Methods

Specified below are 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 logging 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('log', logData => {
  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('log', logData => {
  plugin.log('Received log data')
  plugin.log(logData)

  client.log(logData)
})

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('log', logData => {
  client
    .log(JSON.parse(data))
    .catch(err => {
      plugin.logException(err)
    })
})

Reference Implementations

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

• Splunk Logger
• Loggly Logger
• Logentries Logger
• Sumologic Logger

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