Developing Ensemble Productions Defining Business Metrics [Home] [Back] [Next]

• Introduction to Ensemble Business Metrics
• Defining a Single-instance Business Metric
• Defining a Multi-instance Business Metric
• Other Options in Business Metric Classes
• Adding Business Metrics to Dashboards
• Adding Business Metrics to the Production Monitor
• Setting and Getting Values Programmatically
• About the Business Metric Cache

• It must be a subclass of Ens.BusinessMetric.
  For this class, the ADAPTER parameter is Ens.InboundAdapter, which provides the CallInterval setting. This ensures that the business metric is invoked periodically.
• It must define one or more business metric properties. The details are different for simple properties and properties with autohistory.
• It can optionally specify values for property parameters, for example, to control the range of values.
• It must assign values to the business metric properties. To do so, it must implement the OnCalculateMetrics() method.

Property MetricProperty As Ens.DataType.Metric;

/// This metric tracks A/R totals
Property AccountsReceivable As Ens.DataType.Metric;

Property MetricProperty As Ens.DataType.Metric (AUTOHISTORY=50) [MultiDimensional];

/// Recent Sales History
Property SalesHistory As Ens.DataType.Metric (AUTOHISTORY = 50) [ MultiDimensional ];

/// Total Sales for the current day.
Property TotalSales As Ens.DataType.Metric (RANGELOWER = 0, RANGEUPPER = 50, UNITS = "$US");

/// 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).

• Follow the instructions in the previous section, except that the details are slightly different for implementing OnCalculateMetrics().
• Define the instance names. To do so, you can:
  • Define a static set of instance names. To do so, implement the OnGetInstances() method to assign a fixed list of names to an array. This approach is useful if the set of instances is static.
  • Define the instance names dynamically. To do so, add a MetricInstances() query to get a list of names from a column in an SQL database. This approach is useful if you expect the number or names of the items to change over time.
  • Combine these approaches. Use the MetricInstances() query to get an initial list and then use OnGetInstances() to add or replace names. (The business metric instance calls MetricInstances() first and then calls OnGetInstances().)
• In your implementation of OnCalculateMetrics(), check the value of the %Instance property and assign values to the business metric properties as appropriate for that instance.
• 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.

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

• The query must be named MetricInstances().
• 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
}

1. 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.)
2. Set the values of the business metric properties as needed for that instance.

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
}

Method OnInit() As %Status
{
    // . . .

    // invoke superclass implementation
    Quit ##super()
}

1. Add them to the appropriate production, in the same way that you would add any other business service.
2. Configure the Call Interval setting as needed for each business metric.
3. Create dashboards and add business metrics to them. For information, see Configuring Ensemble.
4. Optionally extend the Production Monitor page to show information from your business metrics. See the next section.

 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"

  Set value = ##class(Ens.BusinessMetric).GetMetric(metric,property)

  Set value(1) = ##class(Ens.BusinessMetric).GetMetric(metric,property,1)

  Set tSC = ##class(Ens.BusinessMetric).SetMetric(metric,property,value)

  For i=1:1:20 {
    Set data(i) = i*i
  }
  Set tSC = ##class(Ens.BusinessMetric).SetMetric("MyMetric","MyGraph",.data)

 ^Ens.Metrics(BusinessMetric,Instance,Property) = value

• BusinessMetric is the configured name of the business metric class.
• 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.