When developing an exhibit there are 3 types of logging that you may see. One type is used internally by the SDK to log messages about the SDK itself (very meta), the other two types are logs that you as the exhibit developer will cue. Below we talk about each, show examples of their output and talk about how they can be managed. At the end we layout some opinions on how to best use these logs in harmony.

The types of logs we will discuss include:

1. Your logs (aka: Exhibit Logs or Local Server Logs)

2. gumbandLocalLogger

3. gumbandCloudLogger

Your Console Log Statements

This one is the easiest. When you are writing your own code and you use console statements you can see those in the node process that is running your exhibit. In the example of The Digital Signage and Game Tutorial we can put some logging statements before and after the socket handlers in addSDKListeners so we know that all of these were mounted.

// gumband-sdk-tutorial/gumband/gumband-service.js
class GumbandService {
    ... instance variables, constructor
  
    /**
     * Add listeners to the Gumband SDK to handle messages from the Gumband Cloud.
     */
    addSDKListeners() {
        console.log('Adding SDK listeners...')
        // 👆  I added this to my exhibit code to know the function is running.
        
        this.gumbandSDK.on(Sockets.OP_MODE_RECEIVED, (payload) => {
            //Body Ommitted
        })
        this.gumbandSDK.on(Sockets.READY, async (manifest) => {
            //Body Ommitted
        })
        this.gumbandSDK.on(Sockets.SETTING_RECEIVED, (payload) => {
            //Body Ommitted
        })
        this.gumbandSDK.on(Sockets.FILE_UPLOADED, async (manifest) => {
            //Body Ommitted
        })
        //listen for the CONTROL_RECEIVED event
        this.gumbandSDK.on(Sockets.CONTROL_RECEIVED, async (payload) => {
*            //Body Ommitted
        });
        
        // 👇 I added this to make sure all of the `.on` methods completed.
        console.log('SDK listeners added.')
    }
}

You can see those logs as I start up the exhibit. They don’t have any decoration or color because in this example, we as the exhibit user didn’t include utilize any external libraries.

Gumband Local Logger

When you install the Gumband SDK there is a module of that package called localLogger. This module is what the Gumband team uses to log information to you (the exhibit developer) regarding the operation of your exhibit into your local console. As an exhibit developer you will NOT make calls to the local logger, but you can control how noisy it’s output is depending on your personal preference.

const { Gumband } = require("@deeplocal/gumband-node-sdk");
this.gumbandSDK = new Gumband(
    process.env.EXHIBIT_TOKEN,
    process.env.EXHIBIT_ID,
    `./manifest.json`,
    {
      // Additional Configuration Options
      localLoggingLevel: 'debug' 
    }
);

The acceptable values for localLoggingLevel:

• debug - the ‘noisiest’ of the logs, it includes all levels of severity listed below in addition to console.debug statements. You probably don’t need this log level unless you’re curious as to how the SDK works “under the hood”.

• info - the second noisiest of the logs, includes all levels of severity below in addition to console.info statements. You may find this useful, even though it increases the volume of logs in your terminal.

• warn - this log level includes the severity below in addition to console.warn statements. It is helpful because this is where we will post notices of future deprecation, tips/tricks or potential “gotchya moments” to keep you aware. This is the default log level if you don’t set anything in the new Gumband() constructor options object.

• error - this level is reserved for the most alarming use cases. We try to use it as little as possible, but when it arrives you should probably double check your code/connections etc to ensure the exhibit is functioning as intended as it’s possible that something is awry.

Gumband Cloud Logs

These log messages can be triggered by the exhibit developer during runtime and, assuming a healthy internet connection, those logs will appear in the Logging Tab of the Gumband Cloud UI. These are independent of the previous logs and will NOT show up in the local console.

You can trigger these logs by calling commands like:

this.gumbandSDK.logger.debug('This is a debug log');
this.gumbandSDK.logger.info('This is an info log');
this.gumbandSDK.logger.warn('This is a warn log');
this.gumbandSDK.logger.error('This is an error log');

You may have seen this if you followed the Digital Signage and Game Tutorial where the tutorial logs to the cloud UI anytime the operating mode or content of the exhibit is changed.

Some Opinions/Suggestions

Suggested Logging Level

First and foremost we recommend leaving the default setting of the local logger to warn. However if you are experiencing any strange behaviors of your code it might be helpful to temporarily increase the logging level to info or debug.

Listening for Sockets.ERROR

The SDK utilizes Websockets for various operations. Within the SDK anytime we encounter a websocket error we emit it to whatever has instantiated a new Gumband() class.

During the running of an exhibit if the SDK encounters an error it will emit Sockets.ERROR via the common EventEmitter from the events module of node. The errors that are emitted in this event can be a result of faulty configurations passed into the Gumband constructor or other functions we provide.

If you are extending the Digital Signage and Game Tutorial you can listen for those events like this:

// gumband-node
const { Gumband, Sockets } = require("@deeplocal/gumband-node-sdk");

/**
 * A class that wraps the Gumband SDK and handles websocket messages 
 * that come from the Gumband Cloud.
 */
class GumbandService {
    /**
     * A reference to the Gumband SDK instance.
     */
    gumbandSDK;

    constructor(window) {
        // Some pieces ommitted for brevity
        
        this.gumbandSDK = new Gumband(
            process.env.EXHIBIT_TOKEN,
            process.env.EXHIBIT_ID,
            `${__dirname}/manifest.json`,
            {
                endpoint: 'local',
                contentLocation: './electron-app/content'
            }
        );
        
        this.addSDKListeners();
    }

    /**
     * Add listeners to the Gumband SDK to handle messages from the Gumband Cloud.
     */
    addSDKListeners() {
        console.log('Adding SDK listeners...')
        // Previous listeners ommited

        //listen for the Sockets.ERROR event
        this.gumbandSDK.on(Sockets.ERROR, async (payload) => {
            // Decide what to do with the error... perhaps send to GumbandCloudUI
            this.gumbandSDK.logger.error(payload)
        });
        console.log('SDK listeners added.')
    }

    // other class methods ommited for brevity
}

module.exports = { GumbandService };

Unified Logging

If as an exhibit developer you want to log to BOTH your local node/exhibit server AND GumbandCloudUI you might find it useful to create a utility yourself. Building on the example Gumband Signage and Game Tutorial might look something like this.

For Example:

// gumband-sdk-tutorial/gumband/gumband-service.js

const { ipcMain } = require("electron");
const { Gumband, Sockets } = require("@deeplocal/gumband-node-sdk");
const fs = require('fs');

/**
 * A class that wraps the Gumband SDK and handles websocket messages 
 * that come from the Gumband Cloud.
 */
class GumbandService {
    // * See Tutorials for the remainder of this class.

    ulog(message, level = 'info') {
        // This takes care of the cloud log.
        this.gumbandSDK.logger.log(message, level);

        // This ensures we have a local log as well.
        console.log(level, message)
    }
}

module.exports = { GumbandService };

Linting

If you decide to implement something like above (ensuring all your server logs are duplicated in GumbandCloudUI) you’ll want to make sure you catch any stray console.* statement. After all a console statement will only end up in your local server logs and NOT in the cloud.

To encourage yourself to use the utility you wrote, you can implement a linting rule within .eslintrc to flag anytime a console.* statement is written.

Check the ESLint Docs to see how to install/configure eslint.

// gumband-project/.eslintrc
{
    ...other Configs
    "rules": {
      "no-console": "warn"
    }
}

This rule will ensure that when you run the linter on the project, the instances of using console.log are highlighted for you to fix! You can always use configuration comments to disable individual instances where you want to suppress those warnings.