Metrics

Overview

To improve the efficiency of your business processes, you often find the need to collect extensive data about the daily workflows and routines within your company. You want to see the specific actions your employees take and the choices they make when achieving outstanding results or when performing poorly, so that you can optimize your processes or tools. The most efficient way for achieving this is through recording relevant data in the form of metrics. Metrics data is also useful for technical purposes like monitoring how well your hardware infrastructure handles the workload or tracking the performance of your applications.

Metrics Pipeline

Generation

Upon initialization, Glue42 Enterprise starts to generate metrics automatically. To control what data you want to receive, you can add configuration for the metrics in the configuration property of the gw top level key of the system.json file, located in %LocalAppData%\Tick42\GlueDesktop\config.

The example configuration below shows how to allow only the User Journey metrics from all publishers and publish them to a local file:

"gw": {
    "configuration": {
        "metrics": {
            "publishers": ["file"],
            "file": {
                "location": "metrics.json",
                "append": false
            },
            "filters": {
                "publishers": [
                    {
                        "publisher": {},
                        "metrics": {
                            "whitelist": [
                                "/ACS/UserJourney"
                            ]
                        }
                    }
                ],
                "non-matched": "blacklist"
            }
        }
    }
}

Glue42 Enterprise offers the following types of out-of-the-box metrics:

Summary Metrics
User Journey metrics
Click Stream metrics
Interop Metrics

We also provide our clients with a way to instrument their own applications to generate metrics. This is achieved through a Metrics API and the generated metrics are called FAV metrics - Feature, Action, Value metrics.

Summary Metrics

Summary Metrics allow you to track how long an application has been on focus. This can be useful when determining which apps are most used/needed.

To enable Summary Metrics, you need to add the following configuration under the metrics top-level key of the system.json file of your Glue42 Enterprise:

"metrics": {
    "summaryMetric": {
        "enabled": true,
        "collectInterval": 30,
        "minimalFocusInterval": 1000,
        "flushOnShutdown": true,
        "debugLoggingEnabled": true
    }
}

enabled - set to true to enable Summary Metrics;
collectInterval - the interval (in minutes) at which to publish the gathered metrics. Cannot be less than 30 minutes.
minimalFocusInterval - the minimal focus time (in ms) for which to record metric data (e.g., if you want to filter out accidental focus of apps);
flushOnShutdown - specifies whether or not to publish the gathered metrics on shutdown;

Summary Metrics are recorded in the form of FAV metrics. Below is an example of a Summary Metric:

{
    "timestamp": 1581341578526, // the time the metric was created;
    "value": {                  // the set of specific information the metric contains;
        "value": {
            "name": {           // name of the application on focus;
                "value": "channelsclientlist"
            },
            "action": {
                "value": "Focused Duration"
            },
            "payload": {        // information about start and end times, application name and focus duration;
                                // from this example, we can see that the "Client List" application has been on focus for 3582 ms;
                "value": "{\"start\":1581334200000,\"end\":1581336000000,\"application\":\"channelsclientlist\",\"focusedDuration\":3582}"
            }
        }
    }
}

User Journey

Information about the User Journey is extremely useful when you want to optimize your workflows. For example, if your employees need to work with several apps to perform their duties, you can collect information about the order in which they typically use the apps for certain tasks. This can provide you with crucial insights on how to plan your work processes, so that your employees can save time, effort and minimize the risk of errors.

The example below shows a user transitioning from the "Client Portfolio" app to the "Client List" app, which will be recorded as a User Journey metric:

User Journey metric capture

And here is how the metric describing the transition from the "Client Portfolio" app to the "Client List" app looks like:

{
    "timestamp": 1568894332012, // the time the metric was created;
    "value": {                  // the set of specific information the metric contains;
        "value": {
            "AppType": {        // application type - Glue42 container or external app;
                "value": "HC"
            },
            "AppName": {        // name of the application;
                "value": "channelsclientlist"
            },
            "PrevAppLostFocus": { // the time when the previous application has lost focus;
                "value": 1568894332011
            },
            "Info": {
                "value": ""
            },
            "PrevAppGotFocus": { // the time when the previous application has gotten focus;
                "value": 1568894328788
            },
            "PrevAppName": {     // the name of the previous application;
                "value": "channelsclientportfolio"
            },
            "Instance": {        // app instance ID within Glue42 Enterprise;
                "value": "9816_10"
            },
            "Action": {          // the action described by the metric - e.g., getting/losing focus, starting/stopping an application;
                "value": "GotFocus"
            },
            "Time": {            // the time the action occured;
                "value": 1568894332012
            }
        }
    }
}

Click Stream

The Click Stream metrics provide you with information about what the user has clicked in the application window. This can be useful in determining the most efficient workflow patterns and best practices when using an application.

Here is how a Click Stream metric may look like when a user clicks on a DOM element in an app:

{
    "timestamp": 1569935517070,     // the time the metric was created;
    "value": {                      // the set of specific information the metric contains;
        "value": {
            "type": {               // the type of the event;
                "value": "click"
            },
            "timestamp": {
                "value": 1569935517070
            },
            "target": {             // the targeted app element;
                "value": {
                    "className": {  // the class of the DOM element, if any;
                        "value": "expand"
                    },
                    "id": {         // the id of the DOM element, if any;
                        "value": "imageWrapper"
                    },
                    "type": {       // the type of the DOM element, if any;
                        "value": "<div>"
                    },
                    "href": {       // the URL the DOM element points to, if any;
                        "value": ""
                    }
                }
            }
        }
    }
}

Interop Metrics

The Glue42 Gateway can be configured to publish Interop related metrics that are subject to black/white listing (methods and arguments). This can be useful when you want to track which application has invoked which method and with what arguments.

Below is an example configuration for publishing Interop metrics to a local file. Data will be collected about all methods whose names start with T42.Wnd (these are actual methods for handling windows in Glue42 Enterprise). Further filtering of the matched methods will be applied in order to exclude metrics about methods which have an argument called email - to avoid leaking personal information.

identity must be present;
interop.enabled must be true;

{
    "metrics": {
        "identity": {
            "system": "Glue",
            "service": "Gateway"
        },
        "publishers": ["raw"],
        ...
        "interop": {
            "enabled": true,
            "invoke": {
                "filters": {
                    "methods": [{
                        "name": "#T42.Wnd.*",
                        "arguments": {
                            "blacklist": ["email"]
                        }
                    }],
                    "non-matched": "blacklist"
                }
            }
        },
        "raw": {
            "location": "metrics.json",
            "append": false
        }
    }
}

Below you can see how an actual Interop metric (structured as a FAV metric) may look like. It shows information about the T42.Wnd.OnEvent streaming method which publishes updates about windows (in this case, it was triggered when a window was closed):

{
    "timestamp": 1570012440145,     // 1
    "value": {                      // 2
        "value": {
            "name": {               // 3
                "value": "interop"
            },
            "action": {             // 4
                "value": "event"
            },
            "value": {              // 5
                "value": "{\"subscription_id\":\"r-91647ca3d11f49c5a41cc8ba466fc1df-45\",
                \"subscriber\":{\"machine\":\"::1\",\"application\":\"js-gns-dialog-panel\",
                \"windowId\":\"848_5\",\"process\":21560,\"user\":\"testUser\",\"instance\":\"i-91647ca3d11f49c5a41cc8ba466fc1df-42\"},
                \"server\":{\"machine\":\"::ffff:127.0.0.1\",\"application\":\"Glue Enterprise\",
                \"applicationName\":\"Glue Enterprise\",\"process\":848,\"user\":\"testUser\",
                \"login\":\"testUser\",\"instance\":\"i-91647ca3d11f49c5a41cc8ba466fc1df-4\"},
                \"method\":\"T42.Wnd.OnEvent\",\"oob\":false,\"sqn\":null,\"snapshot\":null,
                \"data\":{\"type\":\"Closed\",\"windowId\":\"848_6\"}}"
            }
        }
    }
}

timestamp - the time the metric was created;
value - the set of specific information the metric contains;
name - the name of the feature you want to gather information about. In this case - Interop methods;
action - a more specific action you want to track. In this case - Interop events;
value - the recorded information about the specified action. In this case - information about the invoked method (method name, result from the invocation), the instance that has invoked it and contextual system information.

FAV metrics

We also provide our clients with the ability to instrument their applications to generate metrics through a Metrics API. We have named these metrics "Feature, Action, Value metrics", or simply - FAV metrics. Their structure allows you to cover an extremely wide variety of scenarios for collecting and sorting the data you need.

For example, you may have an application which can present information to your clients in two views - a list or a grid view. Now, you want to see which is the preferred view in order to improve the UX of your app. You can instrument your application to generate a FAV metric with the following structure:

Feature	Action	Value
"Info View"	"Selected"	"grid" or "list"

You can use the Feature and Action fields in whatever creative way you may think of to describe the data you are collecting, so that you can later sort it and analyze it. The Value is an object with an arbitrary structure, holding the value(s) you need.

The generated metrics are also injected automatically with meta-data like timestamp and general system, user and application information.

Custom Metrics

We are constantly communicating with our clients in order to improve our product with new features and functionalities. It is, therefore, possible for us to create custom metrics and add them to our product, if the ideas discussed with our clients prove to be useful and of value.

Publishing

The Glue42 Gateway publishes the generated metrics to a server. The means of transporting the generated metrics (REST or a high-speed message queue) depends chiefly on the metrics volume and the available/preferred client infrastructure. The Glue42 Gateway can publish metrics to:

Local file (e.g., for development purposes)
REST service
A user defined JavaScript function
Solace

Publishers

The Glue42 Gateway can be configured to route metrics to one or multiple publishers specified in the configuration. For example, this is how a file-based publisher is configured:

{
    "port": 8080,
    "metrics": {
        "publishers": ["file"],
        "file": {
            "location": "metrics.json",
            "append": false
        }
    }
}

The publishers key specifies a list of metrics publishers, or a JavaScript function accepting the metric to publish, or an instance of RepositoryFactory. Each publisher in the publishers key has its own configuration under a key that matches the publisher name. The currently available publishers are:

file - saves the metrics in a local file. The following configuration properties are available:

key	type	description
`location`	string	The location of the file to write in.
`append`	boolean	Whether to append or overwrite the file.

rest - posts the data to a REST service.

key	type	description
`endpoint`	string	The `REST` URL.
`authentication`	object	Optional object with keys `user` and `password` used for basic authentication.

JavaScript Metrics Publishers

Metrics can be passed to a JavaScript function which handles the publishing. You can define your custom JavaScript publisher function and configure the Glue42 Gateway to pass the metrics to it.

Configuration

Below is an example configuration for enabling a custom JavaScript publisher. The example uses the template file for creating a JavaScript publisher function provided with the Glue42 Enterprise distribution. To add your custom metrics publisher, add a customMetricsPublishers property under gw\configuration in the system.json file of Glue42 Enterprise:

"gw": {
    ...
    "configuration": {
            ...
        "customMetricsPublishers": [
            {
                "file": "%GDDIR%/assets/metrics-publishers/template/index.js",
                "metricsConfiguration": { 
                    "conflating": {           
                        "max-size": 0,            
                        "interval": 1000       
                    },
                    "buffer-size": 10000,        
                    "split-size": 1
                },
                "publisherConfiguration": {
                    "prop": 1
                }
            }
        ]
    }
    ...
}

file - the path to the Node.js module that is to be loaded. You can specify an absolute or a relative path to the .js file;
metricsConfiguration - configurations regarding the exact way the publisher will receive the metrics;
- conflating - the number of metrics to collect before sending them to the publisher and at what interval (in ms) to send them;
- buffer-size - the number of metrics to keep before starting to drop them (e.g., when publishing is slow);
- split-size - the number of pieces the metrics batch is split into when it is pushed to the publisher.
publisherConfiguration - custom configuration options that will be passed as an object argument to the function exported from the Node.js module defined in the file property;

JavaScript Publishing Function

Below is an example skeleton you can use to create your custom JavaScript publisher:

// the function should return an object with three methods

// publisherConfiguration is specified in the system.json file
module.exports = function (publisherConfiguration) {
    function startupFunction() {
        // write your initialization logic here
        // return a Promise indicating when you can start receiving metrics
        return Promise.resolve();
    }

    function cleanupFunction() {
        // write your cleanup logic here
    }

    function handleMetric(metric) {
        // write the code for publishing metrics here
    }

    return {
        startup: startupFunction,
        cleanup: cleanupFunction,
        function: handleMetric
    }
}

startup() - this function should notify you when everything needed to publish the metrics is set up and you can start receiving metrics;
cleanup() - this function should handle the cleanup process after publishing metrics;
handleMetric() - this is the function that publishes the metrics;

Publishing with Solace

Glue42 Enterprise supports publishing metrics via Solace. You can configure the Glue42 Gateway to publish the generated metrics using Solace as a transport.

Configuration

Configuring the Glue42 Gateway to use Solace for publishing metrics is similar to configuring a custom JavaScript publisher.

Here is an example how you can configure the Glue42 Gateway to use Solace to publish metrics:

"gw": {
        ...
    "configuration": {
            ...
        "customMetricsPublishers": [
            {
                "file": "%GDDIR%/assets/metrics-publishers/solace/index.js",
                "publisherConfiguration": {
                    "url": "tcp://localhost:55555",
                    "host": "localhost",
                    "vpn": "default",
                    "password": "",
                    "user": "default",
                    "queue-name": "metrics-queue"
                }
            }
        ]
    ...
}

You need to provide the user credentials (user and password), provide a name for the created message queue (queue-name) and specify the url address to connect to.

Filtering

The Glue42 Gateway allows the metrics and their publishers to be filtered based on white/blacklisting matching on the publisher and metric names. Filtering is useful for targeting only the metrics you would actually consume and to avoid leaking sensitive information.

The filtering configuration has the following syntax:

{
    "metrics": {   
        "filters": {
            "publishers": [<publisher configuration>],
            "non-matched": <non matched configuration>
        }          
    }
}

<publisher configuration> is a Map with the following structure:

{
    "publisher": {<identity key>: <value regex/string>},
    "metrics": {
        "whitelist": [<value regex/string>], 
        "blacklist": [<value regex/string>]
    }
}

To match the publisher, the value of its identity needs to match the regex (or direct string) that is specified in the publisher configuration. For every configuration that is matched, the whitelist and blacklist are checked against the metric name. If a single blacklist or no whitelists match, then the metric will not be published.

If a publisher is not matched, the value specified in the non-matched property will be taken into consideration - it can be either "whitelist" or "blacklist".

A sample configuration that allows only the User Journey and Feature metrics coming from all publishers looks like this:

{
    "metrics": {
        "filters": {
            "publishers": [
                {
                    "publisher": {},
                    "metrics": {
                        "whitelist": [
                            "/ACS/UserJourney",
                            "/App/reporting/features"
                        ]
                    }
                }
            ],
            "non-matched": "blacklist"
        }
    }
}

Below is a configuration that allows all metrics from a publisher whose service starts with "Glue" (note that regex values start with #):

{
    "metrics": {
        "filters": {
            "publishers": [
                {
                    "publisher": {
                        "service": "#Glue.*"
                    },
                    "metrics": {
                        "whitelist": [
                            "#.*"
                        ]
                    }
                }
            ],
            "non-matched": "blacklist"
        }
    }
}

IMPORTANT: Publishers are only going to be "created" on the metrics bus when they have matching metrics.

Storage

Once the metrics are published to a server, they are transformed and routed to the respective storage (or to another transport bus, depending on the client infrastructure and intentions). The transformation is done using the JSLT language. The fields in the JSON files are queried and if they meet certain requirements, the metrics are routed to the respective storage/bus.

Currently, we offer support for RDBMS, ElasticSearch and VaranDB (Tick42 proprietary Cassandra/ElasticSearch high volume solution). We are working on adding support for other options as well.

Visualization

All visualizations and analyses of the gathered information is handled by the client with their preferred tools and infrastructure.

See also our Glue42 Insights product which provides means for aggregation and visualization of the collected metrics information.