|
Developing Ensemble Productions
Defining Business Metrics
|
|
An Ensemble business metric measures or calculates one or more values, typically related to the performance of a production, for display in dashboards or in the Production Monitor. This chapter describes how to create and display business metrics. It contains the following sections:
Note:
As an alternative, you can use third-party business activity monitoring products with Ensemble. These products can interoperate with Ensemble via any of its connectivity technologies, including web services, JDBC, ODBC, and more.
Introduction to Ensemble Business Metrics
A business metric is a specialized
business service class that you include in a production. While the production is running, the business metric values are available for display; when it is not running, the values are null.
Business Metric Properties
The values in a business metric are called
properties. There are two general kinds of business metric properties: simple properties and multidimensional properties with autohistory.
A
simple property holds only one value at any time. The following example displays a business metric with two simple properties:
A
property with autohistory holds multiple values, one value for each point in time, with the most recent value at the end. You can control the number of times when the value is recorded. The following example displays a business metric with two properties that have autohistory:
As a developer of business metric classes, you are free to provide values for metric properties in any manner you choose: such values can be based on data stored within Ensemble messages or business process instances, data maintained within Ensemble by business processes, or data obtained by sending requests to external applications or databases.
Single- and Multi-instance Business Metrics
Also, there are two general kinds of business metrics: single-instance and multi-instance business metrics.
A
single-instance business metric holds a single set of metric values. The examples in the previous section showed single-instance business metrics.
A
multi-instance business metric holds multiple sets of metric values, one set for each instance defined by the metric. Multi-instance business metrics are useful when you have a number of similar items whose metrics you want to compare. Each item is distinct, but has properties in common with the others. For example, each department might have a count of unassigned workflow tasks and a count of assigned workflow tasks. A business metric can have one instance for each department. The following shows an example multi-instance business metric that has two simple properties:
A multi-instance business metric can also have multidimensional properties with autohistory. In practice, however, it is not possible to simultaneously display the instances and the history. If you define such a business metric, then when you add it to the dashboard, the dashboard displays the current values for all instances by default. You can include a filter so that the user can select a single instance; in that case, the dashboard can display the history for that instance.
Then, when a user selects an instance:
Business Metrics as Business Services
All business metric classes are derived from the class
Ens.BusinessMetric, which is itself derived from the
Ens.BusinessService class so that it has the full functionality of a business service. For example, you can add a business metric to a production definition, you can assign a logical name to a business metric, you can schedule it for periodic execution (to recalculate its metric properties at a given interval), and you can invoke business operations and business processes as part of the metric value calculation.
Defining a Single-instance Business Metric
To define a single-instance business metric, define a class that meets the following requirements:
-
-
-
It can optionally specify values for
property parameters, for example, to control the range of values.
-
The following subsections provide the details.
Studio provides a wizard that you can use to create a stub class. To access this wizard, click
and then click
. Select the
Production tab. Select the
Business Metric icon and click
OK.
Defining Simple Business Metric Properties
To define a simple business metric property, add a property to the business metric class as follows:
Property MetricProperty As Ens.DataType.Metric;
This property can hold either numeric or string values.
Where
MetricProperty is the name of the business metric property. For example:
/// This metric tracks A/R totals
Property AccountsReceivable As Ens.DataType.Metric;
This property can hold either numeric or string values.
Defining Business Metric Properties with Autohistory
To define a business metric property with autohistory, add a property to the business metric class as follows:
Property MetricProperty As Ens.DataType.Metric (AUTOHISTORY=50) [MultiDimensional];
For the
AUTOHISTORY parameter, you can use any positive integer. For example:
/// Recent Sales History
Property SalesHistory As Ens.DataType.Metric (AUTOHISTORY = 50) [ MultiDimensional ];
Generally, the purpose of this kind of property is to collect values at intervals, over time, so that the resulting series of numbers can be plotted on a chart. For this reason, the assigned values are typically numeric.
The rate of collection is controlled by the
Call Interval setting of the configured business metric.
Specifying Other Parameters for Metric Properties
You can specify additional property parameters for the business metric properties. These parameters might include default values for the upper and lower limits that control the appearance of any meter that displays that metric. For example:
/// Total Sales for the current day.
Property TotalSales As Ens.DataType.Metric (RANGELOWER = 0, RANGEUPPER = 50, UNITS = "$US");
The following table lists the property parameters that you can use with
Ens.DataType.Metric (in addition to
AUTOHISTORY, which is discussed in the previous section). These parameters apply to metric properties that hold numeric values; none of them apply when the metric property holds a string value.
Assigning Values to Business Metric Properties
This section describes how to assign values to business metric properties for single-instance business metrics; the details for multi-instance business metrics are discussed
later in this chapter.
To assign values to business metric properties, implement the
OnCalculateMetrics() instance method of the business metric class. The purpose of
OnCalculateMetrics() is to calculate, look up, or otherwise set a value for any metric properties in the class.
/// Example Business Metric class
Class MyProduction.MyMetric Extends Ens.BusinessMetric
{
/// Number of times these metrics have been calculated.
Property Counter As Ens.DataType.Metric
(RANGELOWER = 0, RANGEUPPER = 100000, UNITS = "Events");
/// Total Sales for the current day.
Property SalesHistory As Ens.DataType.Metric
(RANGELOWER = 0, RANGEUPPER = 50, AUTOHISTORY = 50, UNITS = "$US")
[ MultiDimensional ];
/// Calculate and update the set of metrics for this class
Method OnCalculateMetrics() As %Status
{
// set the values of our metrics
Set ..Counter = ..Counter + 1
Set ..SalesHistory = $GET(..SalesHistory) + $RANDOM(10) - 5
Quit $$$OK
}
}
-
Notice that you specify the value for a property in the same way for simple properties and for properties with autohistory.
(If you are familiar with multidimensional properties, note that you specify the value only for the unsubscripted top node of the property, as shown here. Because of the
AUTOHISTORY parameter, Ensemble generates code that automatically maintains the lower nodes in the array, which is an integer-subscripted array. For example,
SalesHistory(1) is the oldest value in the
SalesHistory property.)
-
In this method, you can optionally invoke business operations and business processes. You can also invoke any APIs needed to compute the values.
-
Never allow a property with autohistory to contain a null value. The null values are not displayed, causing bar charts and line charts to contain the wrong number of bars or entries. This can result in a mismatch between the axis labels and the items that they label. To prevent such problems, replace any null values with zero.
-
Before the
OnCalculateMetrics() method is called, all metric properties are set to their last calculated value (if any). After the
OnCalculateMetrics() is called, the values of all the metric properties are stored in the business metric cache for subsequent use by dashboards or other interested parties (if any).
Defining a Multi-instance Business Metric
To define a multi-instance business metric:
-
-
Define the instance names. To do so, you can:
-
-
Keep the following principles in mind:
-
The instance names are strings.
-
The instance names must be unique.
-
The instance names may be displayed to users on a dashboard, so use names that are concise, informative, and appropriate.
-
Try to keep the number of instances reasonable. Thousands of instances could be expensive to compute and difficult for users to understand.
The following subsections provide the details.
Defining a Static Set of Instance Names
To define a static set of instance names, override the
OnGetInstances() method. This method is passed an array by reference. The
OnGetInstances() method must fill this array with names using an ordinal number as a subscript, starting with 1. A simple example follows:
/// Return an array of metric instances
ClassMethod OnGetInstances(ByRef pInstSet As %String) As %Status
{
Set pInstSet(1) = "Apple"
Set pInstSet(2) = "Banana"
Set pInstSet(3) = "Cherry"
Quit $$$OK
}
Defining the Instance Names Dynamically
To define the set of instance names dynamically, add a query to the business metric class as follows:
-
-
It must take no arguments.
-
The query must contain an SQL SELECT statement.
-
The first column returned by the query returns the instance names.
/// Return current list of product names
Query MetricInstances() As %SQLQuery
{
SELECT ProductName FROM MyApplication.Product
}
Assigning Values to Properties in a Multi-instance Metric
To assign values to properties in a multi-instance business metric, implement the
OnCalculateMetrics() method. In your implementation, set the values as appropriate for each instance. To do so:
-
Check the value of the
%Instance property. This property equals the name of one of the business metric instances.
(Ensemble automatically processes one instance at a time, sequentially. For each instance, Ensemble executes the
OnCalculateMetrics() instance method.)
-
Set the values of the business metric properties as needed for that instance.
The following shows an example:
Method OnCalculateMetrics() As %Status
{
// get product name
Set product = ..%Instance
// find recent sales using SQL
&SQL(SELECT SUM(Sales) INTO :sales
FROM MyApplication.Product
WHERE ProductName = :product)
// update sales metric
Set ..Sales = sales
Quit $$$OK
}
This example uses the current instance name (
%Instance) in an SQL query to retrieve the most recent sales data for that instance, then writes this data to the
Sales property of the current instance of the class.
Note:
You can also use the
%Instance property elsewhere in the class when you want to substitute the current instance name.
Other Options in Business Metrics
This section describes other options within business metric classes.
Defining Actions for Use in Dashboards
A business metric class can define actions, which you can expose as user options in dashboards. An action can perform a combination of client-side activities (such as filtering and refreshing the dashboard) and server-side activities (such as invoking your own APIs). The action mechanism is quite general.
You can also override the
OnInit() callback of the business metric class, to initialize any properties, for example. If you do so, you must ensure that it explicitly calls the
OnInit() method provided by its superclass
BusinessMetric, as shown below. If not, the corresponding dashboard element does not display properly:
Method OnInit() As %Status
{
// . . .
// invoke superclass implementation
Quit ##super()
}
Adding Business Metrics to Dashboards
To add business metrics to dashboards, do the following:
-
Add them to the appropriate production, in the same way that you would add any other business service.
-
Configure the
Call Interval setting as needed for each business metric.
-
-
Adding Business Metrics to the Production Monitor
In addition to displaying business metrics in dashboards, you can extend the
Production Monitor page to show information from your business metric classes. To do so, set nodes in the
^Ens.Monitor.Settings global in your namespace, as follows:
For example, do the following in the Terminal:
Set ^Ens.Monitor.Settings("MetricClasses",1,"Metric") = "MetricConfigName"
Set ^Ens.Monitor.Settings("MetricClasses",1,"Title") = "Title for Display"
Set ^Ens.Monitor.Settings("MetricClasses",1,"Instance") = "MetricInstanceName"
For each business metric that you add, the Production Monitor page indicates when it last updated the metric information, if there is any data for the given metric or instance, and whether or not the given metric is currently running.
Setting and Getting Values Programmatically
Using the GetMetric() Method
The
GetMetric() class method reads the current value of a specified metric property from the business metric cache. Call this method as follows:
Set value = ##class(Ens.BusinessMetric).GetMetric(metric,property)
Where
metric is the name of the business metric (the configuration name, not the class name) and
property is the name of the metric property. If
GetMetric() is unable to read the specified value, it returns an empty string.
To read values from multidimensional metric properties, there is a third, optional parameter that specifies which subnode of the property to read. For example:
Set value(1) = ##class(Ens.BusinessMetric).GetMetric(metric,property,1)
Using the SetMetric() Method
The
SetMetric() class method sets the value of a specified metric property within the business metric cache. Call this method as follows:
Set tSC = ##class(Ens.BusinessMetric).SetMetric(metric,property,value)
Where
metric is the name of the business metric (the configuration name, not the class name),
property is the name of the metric property, and
value is the value to which the metric property should be set.
To set all the values of a multidimensional metric property, create the array of values and then pass the array by reference. For example:
For i=1:1:20 {
Set data(i) = i*i
}
Set tSC = ##class(Ens.BusinessMetric).SetMetric("MyMetric","MyGraph",.data)
About the Business Metric Cache
So that Ensemble can retrieve metric values as efficiently as possible, it stores these values in a cache. This cache is the global
^Ens.Metrics, which has the following structure:
^Ens.Metrics(BusinessMetric,Instance,Property) = value
-
-
Instance is an instance number. Instances are numbered in the order in which they are defined.
-
Property is the name of the business metric property.
