Principles

HPA agent allows the creation of custom metrics, meaning customer can create and send new time series of numerical values to HPA portal

The way to implement custom metrics can cover a wide range, for stability and easy implementation two use cases only are presented:

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

Prerequisites

To achieve this, those steps are required:

Identify the class and method to observe
Define the metric have to produce
- Its name
- Its type: average response time or count
Create a PBD configuration file
- Defining the metric name and referencing the expected class and method
Create a groovy configuration file
- Defining the additional code played in memory by the agent made to capture the additional information
- Standard groovy file

Metric name

The choice of the metric name will drive how this new metric will be included into the metrics tree - it is then recommended to coordinate with Hexagon support first

Depending on the use case, it is possible to:

Add the metric in HPA existing metrics tree - for example:
- a custom engine to appear in the engines list - Frontends|Apps|HpaEngine-xxx of the EngineServer agent
- a custom thread to appear for a scheduled tasks - Frontends|Apps|xxx of the ScheduledTask agent
Create a customer’s own subtree of metrics - replacing Hpa by a reference to the customer:
- <Customer>|ReportGeneration|ExportEOD-1:count
- <Customer>|TibcoQueue|ReceivedMessage:Average Respone time (ms)

Implementation

Custom metrics files are stored under: <HPA agent dir>/override_config/customMetrics.
If this directory is created while the monitored service is already started, a restart is required.

Groovy file

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

For example: <HPA agent dir>/override_config/customMetrics/cst-scripts/cst_customermetric_my_new_metric.groovy

Count number of executions

At each method execution end, the new metric is sent with the 1 value

Groovy code to consider - only for executeFinish

MetricHelper.sendMetricInterval - sends the expected data to the portal
- First parameter - the agent itself - nothing to change
- Second parameter - the new metric name
  - The start of the metric name will match the agent name and is completed automatically by the agent
- Third parameter - the value of the metric
  - In this case, 1 is “fixed” - nothing to change
- The usage of this MetricHelper method implies the agent sums the values sending the data to the Hpa portal

Content of the file for counting the number of executions 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) {
    }

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

Average response time

At each start of the method execution, the start time is stored, at each end of the method execution, the time difference is sent.

Groovy code to consider - executeStart

MetricHelper.storeWallClockStartTimeHpa(invocationData) - nothing to change - its stores the start time of the method in memory

Groovy code to consider - executeFinish

the elapsed time of the method is captured
in case of asynchronous method execution, nothing is recorded
MetricHelper.sendMetricAverage - sends the expected data to the portal
- First parameter - the agent itself - nothing to change
- Second parameter - the new metric name
  - The start of the metric name will match the agent name and is completed automatically by the agent
- Third parameter - the value of the metric
  - referring to the elapsed time in this case
- The usage of this MetricHelper method implies the agent averages the values sending the data to the Hpa portal

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 for instrumenting a method, i.e. for executing the executeStart and executeEnd groovy methods for this method

Create a PBD file, for example: <HPA agent dir>/override_config/customMetrics/my_new_custom_metric.pbd

With the following content :

Define and activate (or not) this new metric
- A new flag name to consider : no space, it is recommended to prefix it by customer name, e.g. CustomerMyNewMetric
- This new flag appearing then in the agent settings screen
The class and method name, e.g. <class to monitor> and <method to monitor>
The reference to the groovy script previously defined, e.g. cst_customermetric_my_new_metric.groovy

Full example of content of a PBD file

SetFlag: CustomerMyNewMetric
TurnOn: CustomerMyNewMetric

IdentifyInheritedAs: <class to monitor> CustomerMyNewMetric

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

As it is not possible to test groovy, PBD and PBL files without Calypso and traffic, it is recommended to check the agent logs looking for error message (parsing error on groovy or PBD…)

HPA Portal sections Custom metrics management Custom metrics