Using iKnow
Custom Metrics
[Back] [Next]
Go to:

You can customize iKnow to allow users to add their own custom metrics for entities, CRCs, CCs, paths, sentences and/or sources. These metrics can be populated for all sources in the domain, or for select sources. You can then query by these custom metric values.

Custom Metrics software is a Technology Preview, a new category of software at 2013.1. A Technology Preview is intended as a way of introducing and providing access to new software capabilities that InterSystems believes will be useful in enhancing the effectiveness of existing and future applications.
The capabilities listed here are ready for use by customers, but they are not yet complete in functionality and design. Customers who take advantage of these capabilities must understand:
InterSystems strongly encourages those who incorporate these items in their software to provide feedback on their experiences.
Implementing Custom Metrics
Implementation of custom metrics involves the following steps:
  1. Define a metric: To define one or more metrics, implement a subclass of %iKnow.Metrics.MetricDefinition and add an XData block named “Metrics” that specifies the properties for one or more custom metrics.
  2. Define the metric computation: To compute the values of these metrics, implement the calculations in a %iKnow.Metrics.MetricBuilder subclass. This subclass should implement one or more of the Calculate***Metrics() methods to support calculating custom metrics for the corresponding target and type. For example, CalculateEntUniMetrics() calculates a metric targeting entities, applicable to the whole domain.
  3. Register the metric definition: To associate a metric definition with a particular domain, call the Register() method of the %iKnow.Metrics.MetricDefinition class to register your %iKnow.Metrics.MetricBuilder subclass as the "builder class" in the definition. This registers all metrics, their properties and targets, as defined in the “Metrics” XData block. Registering the metric definition configures any data structures required to store the metric values.
    If the domain was created as a subclass of %iKnow.DomainDefinition and metrics were defined for the domain, you do not have to call the Register() method to register your metric definition.
  4. Build the metric values: To build the metric values using a %iKnow.Metrics.MetricBuilder implementation, call the Build() or BuildAll() method of the builder class. These methods build all applicable metrics, forwarding the actual metric calculations to the Calculate***Metrics() implementations. You can specify a filter to limit the custom metrics build to a defined subset of sources.
    Unless your %iKnow.Metrics.MetricBuilder subclass overrides the SUPPORTSMULTIPROCESS parameter (default = 1), the Build() method will divide the work over multiple processes, each instantiating separate MetricBuilder objects and processing batch after batch of entries using those builder objects. For source-indexed target types, these are batches of sources, for which all the target elements are processed by the same builder process.
  5. Optimize the build process: %iKnow.Metrics.MetricBuilder provides a number of callback utility methods, such as OnBeforeBuildMetrics(), OnBeforeBuildMetricsBatch(), OnBeforeBuildMetricsForSource() and the corresponding OnAfter***() methods that can help in optimizing performance by pre-calculating values for a whole batch, which are then selected in the individual Calculate***Metrics() methods. The individual Calculate***Metrics() methods return their values through an output parameter pValues, which is to be populated indexed by metric name (as a single MetricBuilder class can support and calculate multiple metrics in one pass): pValues("MyMetric") = [MyValue].
  6. Get the results: %iKnow.Metrics.MetricAPI provides a number of methods that you can use to interact with custom metrics registered in a particular domain. You can use these methods to return the custom metrics results.
    When Calculate***Metrics() methods don't return any values for a particular target element, the existing metric value is retained (if any). Returning "" for a value will overwrite (erase) the existing value.
For examples, refer to the Aviation.Metrics.Builder and the Aviation.Metrics.Definition classes in the SAMPLES namespace.
Types and Targets
Copying Metrics
You can copy metrics from one domain to another within the current namespace.