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, as to 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

Glue42 Enterprise starts to generate metrics automatically when initialized. To control what data you want to receive, 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:

• Performance Metrics
• Summary Metrics
• User Journey Metrics
• Click Stream Metrics
• Interop Metrics Metrics

You can instrument your own applications to generate metrics. This is achieved through a Metrics API and the generated metrics are called FAV Metrics - Feature, Action, Value metrics.

The table below shows what string values (regex values start with #) to use in the whitelist array to allow the type of metrics you are interested in:

The "/App/reporting/features" value enables publishing FAV Metrics. The same value is used for enabling Summary and Interop Metrics, because they are published in the form of FAV Metrics. See also Interop Metrics for the additional configuration required to enable the Interop Metrics.

Performance Metrics

Performance Metrics are relevant only to web apps. They measure memory usage and statistics related to web app resources and navigation.

Below is an example of a Performance Metric:

{
    "timestamp": 1600347688676,     // The time the metric was created.
    "value": {                      // Information about the JS Heap memory size.
        "value": "{\"totalJSHeapSize\":10317445,\"usedJSHeapSize\":8357333}"
    }
}

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. The configuration for the Summary Metrics is 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.
                                // This example shows that the "Client List" application has been on focus for 3582 ms.
                "value": "{\"start\":1581334200000,\"end\":1581336000000,\"application\":\"channelsclientlist\",\"focusedDuration\":3582}"
            }
        }
    }
}

User Journey Metrics

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:

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 Metrics

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
        }
    }
}

See below 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,     // The time the metric was created.
    "value": {                      // The set of specific information the metric contains.
        "value": {
            "name": {               // The name of the feature you want to gather information about. In this case - Interop methods.
                "value": "interop"
            },
            "action": {             // A more specific action you want to track. In this case - Interop events.
                "value": "event"
            },
            "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.
                "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\"}}"
            }
        }
    }
}

FAV Metrics

You can instrument your applications to generate metrics through a Metrics API. These metrics are named FAV Metrics - "Feature, Action, Value" 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. You want to see which is the preferred view in order to improve the UX of your app. Instrument your application to generate a FAV Metric with the following structure:

Use the Feature and Action fields in whatever creative way you may think of to describe the data you are collecting in order to sort it and analyze it later. 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:

• rest - posts the data to a REST service.

JavaScript Metrics Publishers

Metrics can be passed to a JavaScript function which handles the publishing. It is possible to 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 (absolute or relative) to the Node.js module that is to be loaded;

• 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.

// The `publisherConfiguration` is specified in the `system.json` file.
module.exports = function (publisherConfiguration) {
    function startupFunction() {
        // Write your initialization logic here.
        // Return a `Promise` indicating when to 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 metrics can be received;
• 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.

Below is an example of configuring 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"
        }
    }
}

Note that publishers are going to be created on the metrics bus only 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, support is offered for RDBMS, ElasticSearch and VaranDB (Tick42 proprietary Cassandra/ElasticSearch high volume solution). Support for other options is being developed as well.

Visualization

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

See also the Glue42 Insights product which provides means for aggregating and visualizing the collected metrics information.