Logcaster: A Client-Side Event Logger

Client-side logging and log management is an important tool for analyzing and fixing breaking changes introduced in production, in addition to providing other critical information for keeping our fingers on the pulse of the application's heartbeat. While console-based logging has been the convention thus far, this approach has fundamental limitations when it comes to preserving logs, as well as the format of that logged data. Due to these limitations, it only has value for local development at best.

A more robust approach that also supports user-logs in production is necessary.

This blog will provide a summary of our client-to-server logging architecture, designed with attention towards sending attributes that are useful for the tracking and filtering of preserved data later on. We also designed the logger so as to not be network greedy - only sending the most important logs with priority, taking a more staggered approach to non-priority logs.

The end result will be a more practical way of tracking client-side events within your application's ecosystem. Below I will summarize the architectural thinking and implementation patterns for the logger package.

What are we logging?

The appropriate use of logging levels can make all the difference in the world when reproducing what steps a user took. Once we have lots and lots of log entries in the back end, finding the information we need can be like searching for a needle in a haystack. In an effort to prevent this, we are suggesting the below logging levels. If developers use them carefully when logging events, they will allow us to quickly filter and easily distinguish between serious errors and routine usage.

1. CONSOLE. Information that is diagnostically helpful to developers (and others such as SysAdmins, IT Support, DevOps, etc). Prints to the UI, similar to *console.log*
2. STATE. Taken from the Vuex store management pipeline, we will use this feature to log dispatched actions - potentially useful as a historical snapshot of the application's state at any given moment in time.
3. INFO. Generally useful information to log (service start/stop, configuration assumptions, etc). Info you want to always have available but usually don't care about under normal circumstances. This should be your out-of-the-box config level.
4. WARN. Anything that can potentially cause application oddities, but for which you are automatically recovering. (Such as switching from a primary to backup server, retrying an operation, missing secondary data, etc.)
5. ERROR. Any error which is fatal to the operation. They can be developer-identified (such as a required file is inaccessible, missing data, etc.) or a caught exception. These errors will be flagged as high-priority and will force user (administrator, devops) intervention.

Logging Rules

Under the hood, the Client Logger is sending the above logged events to the server. But, we want to be careful - we don't want to impact the application with "overlogging". A bettter approach is to buffer log entries and send them in batches. A common approach is to use localStorage to store log entries, then send them at particular intervals — in our case when a certain threshold in the number of pending entries is reached, or when an error is thrown.

Below is a pseudo-code representation of the logger:

In short, the above logic is sending logs to the server when an error is hit, the local storage buffer threshold is reached, or we are telling the service to send everything immediately. Otherwise, we are logging to console, localstorage, or the store.

Where are we sending our logs?

Where you send your log messages is up to you. Most if not all log management servers expose an endpoint for inbound messages. We will use such an endpoint to transmit our log buffer according to the rules we have outlined above. In the below VueJS example, we are creating a global logger object in the applications context.

export default ({ Vue }) => {
  Vue.prototype.$clientLogger = ClientLogger.createLogger('global_logger',
      'http://localhost:3000/v1/logs');
};

The parameters we are passing to the createLogger instance are as follows:

1. featureName. - This is the global feature name. It binds every log to the *global_logger* name, making filtering more effective. If you are instantiating the logger in a component constructor, you may want to pass in the component name to provide more detail for filtering log data.
2. apiEndpoint - This is the route to the Clinical UI Server. The Node service that receives log messages and inserts them into stackdriver.
3. immediateSend - The optional *immediateSend* boolean allows us to send all logs to the server without immediately, bypassing local storage.

How to implement logging?

Now, how you call the logging feature is up to you. You may want to reference the npm module and call a local instance of the client logger. For example, you may decide to create a new ClientLogger instance when your component loads and access the instance methods accordingly. However, my preference is to se the logger globally in the context of the application. For example, using VueJS and Quasar as our example frameworks, we can place the ClientLogger class in the /boot directory, making it available throughout the application runtime. Developers can now log messages as they see fit, using the global *$clientLogger* variable in their components.

An example might look like this:

methods: {

    // send info
    someComponentMethod() {
        return something().then(res => {
                this.$clientLogger.info('sending info');
                return res.data;
        });
    }

    // send error
    someComponentMethod() {
            return something().then(res => {
                return res.data;
            })
            .catch(err => {
                this.$clientLogger.error(err);
            });

    }

    // dispatch to vuex
    someComponentMethod() {
         return something().then(res => {
                this.$clientLogger.state(res.data);
                return res.data;
        })
    }

    // send warning
    someComponentMethod() {
        return something().then(res => {
            if (res.data.study_type === '')
                this.$clientLogger.warn('study type not provided');
            return res.data;
            })
    }

    // send to console
    someComponentMethod() {
        return something().then(res => {
            this.$clientLogger.console('the response is: ', res.data);
            return res.data;
        });
    }
}