overlock-nodejs v1.1.2

Overlock Node.js library

The overlock Node.js library should allow logging of messages from the device, as well as on behalf of other devices and with associations.

NOTE: Unfortunately there is a concept of nodes in Overlock, which somewhat complicates references to node in this document. Wherever we mean Node.js, we will state it explicitly. All other references to node, are Overlock nodes.

API Docs

Install

The overlock library needs to have install called. This will patch on to console.log et al. in order to automatically pick up existing log messages in your application. This can be disabled.

import ol from 'overlock'

ol.install('node-process-name', { metadata: { version: '2.1.0' } })

Signature ol.install(processName, opts)

• processName A string, which is the name of the process
• opts An object with keys:
  • metadata An Object, which has key/value information
  • disableConsoleLog Boolean. Default false. If True, messages from console.log will not be picked up by overlock.
  • jsonReplacer A custom function to pass to JSON.stringify when encoding state
  • agentHostname A string. Defaults to localhost
  • agentPort A number. Defaults to 6837

Logging

Logging is the primary way to capture information about the execution of a program in overlock.

Example:

// Basic logging
ol.log('This is a log message')

// Log as device
ol.log('This is as a different device', { logAs: 'device123' })

// Log with related device
ol.log('This is associated with the other node too', { related: 'device234' })

// Log with a level
ol.log('This is an error', { severity: 100 })

// Also with a pre-set level
ol.error('This is an error')

Signature:

ol.log(msg, opts)

• msg A string, which contains a message to debug
• opts An object with keys:
  • severity: The log level (goes straight to agent API)
  • logAs: Log as if the message were from another node
  • related: Log with an association

ol.error, ol.warn, ol.debug, ol.info should all just be proxies to log with the log level set.

Lifecycle

Lifecycle events can be logged to allow high level information and events to be captured.

// Lifecycle event
ol.lifecycleEvent('boot', 'Booted up')

// For another device
ol.lifecycleEvent('network-disconnect', 'Unexpected Disconnected!', { logAs: 'device234' })

Signature:

ol.lifecycleEvent(type, msg, opts)

• type A string type for a supported or custom lifecycle event
• msg A string which describes the event
• opts An object with keys:
  • logAs: Log as if the message were from another node
  • related: Log with an association

Metadata

Allows storing of values about a node which do not change very often.

ol.updateMetadata({ version: '10.000' })

// For another device
ol.updateMetadata({ version: '10.000' }, { logAs: '12345' })

Signature:

ol.updateMetadata(values, opts)

• values An object which contains the keys to merge in to the metadata. Values will be converted to strings, and Falsy values will be removed from metadata.
• opts An object with keys:
  • logAs: Log as if the message were from another node

Setting state

// set a key
ol.updateState({ sensor: 120 })

// delete a key
ol.deleteState({ sensor: false })

// As another device
ol.updateState({ sensor: 120 }, { logAs: '12345' })