Principles

HPA agent permits the creation of custom metrics, meaning customer can create and send a numerical value to HPA portal.

The way to implement custom metrics can cover a wide range, for stability and easy implementation we reduce the scope to a simple use cases :

record the execution time of Java method
record the number of execution of a Java method

Prerequisites

To achieve this, follow the steps :

Identify the class and method to observe
Identify which metric have to be produced 3. A name 4. average response time or count
Create a PBD configuration file
Create a groovy configuration file

Metric name

Coordinate with Hexagon support for this part.
According to the use case, it is possible :

Add the metric in HPA existing metrics tree. For example :
- a custom engine to appears in the engines list
- a custom thread to appears in the frontends of a scheduled tasks
Create a customer’s own subtree of metrics :
- <Customer>|ReportGeneration|ExportEOD-1:count
- <Customer>|TibcoQueue|ReceivedMessage:Average Respone time (ms)

Implementation

Custom metrics files are store under : <agent home>/wily/core/config/hpacustomer

Add a groovy file

Create a groovy file that will produce the metrics, in subdirectory cst-scripts.

For example : <agent home>/wily/core/config/hpacustomer/cst-scripts/cst_customermetric_my_new_metric.groovy

Count number of executions

Here, very simple : at each method end of execution, we send the number of execution of the metrics.
Take care of MetricHelper.sendMetricInterval : it sends counter metrics

Content of the file for counting an execution method :

import com.hexagon.wily.scripting.executor.HpaNonBlameExecutor
import com.wily.introscope.agent.IAgent
import com.wily.introscope.agent.trace.InvocationData
import com.wily.util.feedback.IModuleFeedbackChannel
import com.hexagon.wily.scripting.MetricHelper

class CustomerMyNewMetric implements HpaNonBlameExecutor {

    @Override
    void executeStart(InvocationData invocationData, IAgent agent, IModuleFeedbackChannel log, String scriptname) {
    }

    @Override
    void executeFinish(InvocationData invocationData, IAgent agent, IModuleFeedbackChannel log, String scriptname) {
        MetricHelper.sendMetricInterval(agent, <Customer>|ReportGeneration|ExportEOD-1:count", 1);
    }
}

Average response time

Here, also simple : at each method start of execution, record the start time. We send the execution time at the end.
Take care of MetricHelper.sendMetricAverage : it sends an average metrics

Content of the file for measuring an execution time of a method :

import com.hexagon.wily.scripting.executor.HpaNonBlameExecutor
import com.wily.introscope.agent.IAgent
import com.wily.introscope.agent.trace.InvocationData
import com.wily.util.feedback.IModuleFeedbackChannel
import com.hexagon.wily.scripting.MetricHelper

class CustomerMyNewMetric implements HpaNonBlameExecutor {

    @Override
    void executeStart(InvocationData invocationData, IAgent agent, IModuleFeedbackChannel log, String scriptname) {
        MetricHelper.storeWallClockStartTimeHpa(invocationData);
    }

    @Override
    void executeFinish(InvocationData invocationData, IAgent agent, IModuleFeedbackChannel log, String scriptname) {
        long elapsedTime = MetricHelper.getWallClockElapsedTimeHpa(invocationData);
        if (elapsedTime == -1) {
            return; // Async execution, No start time recorded
        }
        MetricHelper.sendMetricAverage(agent, <Customer>|ReportGeneration|ExportEOD-1:Average Response Time (ms)", elapsedTime);
    }
}

Add a PBD file

The PBD is responsible of instrument a method, i.e execute the methods executeStart and executeEnd on a method.

Create a PBD file, for example : <agent home>/wily/core/config/hpacustomer/my_new_custom_metric.pbd

With the following content :

Choose a name for the flag : no space, we recommend to prefix it by customer name, in this example : CustomerMyNewMetric
The class and method name, in this example : <class to monitor> and <method to monitor>
Choose a name for the groovy script that will produce the metric, here cst_customermetric_my_new_metric.groovy

SetFlag: CustomerMyNewMetric
TurnOn: CustomerMyNewMetric

IdentifyInheritedAs: <class to monitor> CustomerMyNewMetric

TraceOneMethodWithParametersIfFlagged: CustomerMyNewMetric <method to monitor> HpaMetricOnlyTracer "{@cst_customermetric_my_new_metric.groovy}"

Activate the PBD file

To activate the PBD file, simply add it at the end of :

<agent home>/wily/core/config/hpacustomer/hpa_customerconfig.pbl

For example :

#####
# Add here your custom directives.
# Be sure to valide it with Hexagon support team

# Example : custom_metric.pbd
# Example : other_set_of_custom_metrics.pbd

my_new_custom_metric.pbd

Hot reloading

By default, as soon as PBD or PBL files are modified, in the next minutes the modification is applied.

Note that for performance reason, groovy script is compiled only once and can not be modified without renaming

Check the agent logs to check error information (parsing error on groovy or PBD…)

HPA Portal sections Custom metrics Custom metrics