// ==================================================================
// Title:       Metrics MOF Specification 2.7, Base Metrics
// Author:      DMTF Application Working Group
// Filename:    Metric27_BaseMetric.MOF
// Version      2.7.0
// Status:      Final
// Date:        31 March 2003
// ===================================================================
// Copyright 1999-2003 Distributed Management Task Force, Inc. (DMTF).
// All rights reserved.  
// DMTF is a not-for-profit association of industry members dedicated 
// to promoting enterprise and systems management and interoperability. 
// DMTF specifications and documents may be reproduced for uses
// consistent with this purpose by members and non-members, 
// provided that correct attribution is given. 
// As DMTF specifications may be revised from time to time, 
// the particular version and release date should always be noted.
//
// Implementation of certain elements of this standard or proposed 
// standard may be subject to third party patent rights, including 
// provisional patent rights (herein "patent rights"). DMTF makes 
// no representations to users of the standard as to the existence 
// of such rights, and is not responsible to recognize, disclose, or
// identify any or all such third party patent right, owners or 
// claimants, nor for any incomplete or inaccurate identification or 
// disclosure of such rights, owners or claimants. DMTF shall have no 
// liability to any party, in any manner or circumstance, under any 
// legal theory whatsoever, for failure to recognize, disclose, or 
// identify any such third party patent rights, or for such party's
// reliance on the standard or incorporation thereof in its product, 
// protocols or testing procedures. DMTF shall have no liability to 
// any party implementing such standard, whether such implementation 
// is foreseeable or not, nor to any patent owner or claimant, and shall 
// have no liability or responsibility for costs or losses incurred if 
// a standard is withdrawn or modified after publication, and shall be
// indemnified and held harmless by any party implementing the 
// standard from any and all claims of infringement by a patent owner 
// for such implementations.
//
// For information about patents held by third-parties which have 
// notified the DMTF that, in their opinion, such patent may relate to 
// or impact implementations of DMTF standards, visit 
// http://www.dmtf.org/about/policies/disclosures.php.
// ===================================================================
// Description:
//    Additions to the V2.6 Metrics MOF to support a more generic
//    approach.
//
//    CIM users often desire metric objects that model designers have not
//    provided. Furthermore, such needs vary from one management philosophy
//    to another. Rather than fill more and more CIM models with
//    standardized objects, the Metrics model supports externally defined
//    expressions of existing objects, such as properties of 
//    CIM_StatisticalData and its subclasses. In addition, the 
//    classes described in this file enable users to define their own
//    metrics at runtime (rather than at provider implementation time).
//    A newly defined metric (aka CIM_BaseMetricDefinition) may be
//    given a value by instantiating CIM_BaseMetricValue. 
//    Both CIM_BaseMetricDefinitions and CIM_BaseMetricValues may be
//    associated with a ManagedElement.
// ==================================================================
// CIM 2.7.0 (Preliminary) 5 June 2002
//     CR820 - Defined Base Metrics Classes and associations
//     CR851 - Change the Description of BaseMetricValue.Duration 
//             to define the timestamp as the end of the duration
// CIM 2.7.0 (Final) 17 March 2003
//     CR987 - Remove experimental qualifier from:
//              -CIM_BaseMetricDefinition
//              -CIM_BaseMetricValue
//              -CIM_MetricInstance
//              -CIM_MetricDefForME
//              -CIM_MetricForME
// ==================================================================

#pragma Locale ("en_US")


// ================================================================== 
// BaseMetricDefinition
// ==================================================================
      [Version("2.7.0"), Description (
        "CIM_BaseMetricDefinition represents the definitional aspects "
        "of a metric, i.e., a definition template containing meta data "
        "about a new metric. Since CIM_BaseMetricDefinition does not "
        "capture metric instance information, it does not contain the "
        "value of the metric. The associated class CIM_BaseMetricValue "
        "holds the metric value and encapsulates its runtime behavior. "
        "The purpose of CIM_BaseMetricDefinition is to provide a "
        "convenient mechanism for introducing a new metric definition at "
        "runtime and capturing its instance values in a separate class. "
        "This mechanism is targeted specifically at CIM users who "
        "would like to enhance existing CIM schemas by introducing "
        "domain-specific metrics that are not captured in the existing "
        "CIM schemas. In addition, vendors of managed resources may make "
        "use of this mechanism if a small subset of a potentially large "
        "and heterogeneous amount of performance-related data needs to "
        "be exposed, based on the context in which the data is captured. "
        "Additional meta data for a metric can be provided by "
        "subclassing from CIM_BaseMetricDefinition. "
        "The CIM_BaseMetricDefinition should be associated with "
        "the CIM_ManagedElement(s) to which it applies.") ] 
class CIM_BaseMetricDefinition : CIM_ManagedElement {

      [Key, Description (
          "A string that uniquely identifies the metric definition. "
          "The use of OSF UUID/GUIDs is recommended.") ]
   string Id;

      [Description (
          "The name of the metric.  This name does not have to be "
          "unique, but should be descriptive and may contain "
          "blanks.") ]
   string Name;

      [Description (
          "The data type of the metric. For example, \"boolean\" "
          "(value=1) or \"datetime\" (=3) may be specified. These" 
          "types represent the datatypes defined for CIM."),
       ValueMap {"1", "2", "3", "4", "5", "6", "7", "8", "9", "10", 
          "11", "12", "13", "14" },
       Values  {"boolean", "char16", "datetime", "real32", "real64",    
          "sint16", "sint32", "sint64", "sint8", "string", "uint16",
          "uint32", "uint64", "uint8"} ]
    uint16 DataType;

      [Description (
          "An enumerated value that describes the characteristics "
          "of the metric, for purposes of performing calculations. "
          "The property can take one of the following values: \n"
          "1=\"Non-calculable\" -> a string. Arithmetic makes no "
          "sense. \n"
          "2=\"Summable\" -> It is reasonable to sum this value over "
          "many instances of e.g., UnitOfWork, such as the number of "
          "files processed in a backup job. For example, if each backup "
          "job is a UnitOfWork, and each job backs up 27,000 files on "
          "average, then it makes sense to say that 100 backup jobs "
          "processed 2,700,000 files. \n"
          "3=\"Non-summable\" -> It does not make sense to sum this "
          "value over many instances of UnitOfWork. An example would be "
          "a metric that measures the queue length when a job arrives "
          "at a server. If each job is a UnitOfWork, and the average "
          "queue length when each job arrives is 33, it does not make "
          "sense to say that the queue length for 100 jobs is 3300. It "
          "does make sense to say that the mean is 33."),
       ValueMap {"1", "2", "3" },
       Values {"Non-calculable", "Summable", "Non-summable"} ]
    uint16 Calculable;

      [Description (
          "Identifies the specific units of a value. Examples are Bytes,"
          "Packets, Jobs, Files, Milliseconds, and Amps.") ]
    string Units;

      [Description (
          "Defines one or more strings that can be used to refine "
          "(break down) queries against the BaseMetricValues along "
          "a certain dimension. An example is a transaction name, "
          "allowing the break down of the total value for all "
          "transactions into a set of values, one for each transaction "
          "name. Other examples might be application system or user "
          "group name. The strings are free format and should be "
          "meaningful to the end users of the metric data. The "
          "strings indicate which break down dimensions are "
          "supported for this metric definition, by the underlying "
          "instrumentation.") ]
    string BreakdownDimensions[];
};


// ================================================================== 
// BaseMetricValue
// ==================================================================
      [Version("2.7.0"), Description (
        "   Each CIM_BaseMetricValue object represents the instance "
        "value of a metric. Since the gathering of metric information "
        "can involve large quantities of information there may be many "
        "instances of this class. The use of this class as an "
        "instrumentation source may be inefficient unless the rate of "
        "metrics are known. The length of time a CIM_BaseMetricValue "
        "instance exists after the metric information is captured is "
        "not defined and is implementation dependent. \n"
        "   Most metric data values change over time. There are two "
        "ways of mapping this into CIM_BaseMetricValue objects: The "
        "value for the next point in time may use the same object and "
        "just change its properties (such as the value or timestamp), "
        "or the existing objects remain unchanged and a new object is "
        "created for the new point in time. The first method is "
        "typically used for snapshot data and the second method for "
        "historical data. Which method is used, is indicated by the "
        "Volatile property.") ] 
class CIM_BaseMetricValue : CIM_ManagedElement {

      [Key, Description (
          "A unique identifier of this instance of the metric "
          "value. This must be a globally unique identifier.") ]
   string InstanceId;

      [Required, Description (
          "The key of the BaseMetricDefinition instance for this "
          "CIM_BaseMetricValue instance value."),
       ModelCorrespondence {
          "CIM_BaseMetricDefinition.Id"} ]
   string MetricDefinitionId;

      [Description (
          "   A descriptive name for the element to which the metric "
          "value belongs (i.e., the measured element). This property "
          "is required by behavior if there is no association defined "
          "to a ManagedElement, but may be used in other cases to "
          "provide supplemental information. This allows metrics to "
          "be captured independently of any ManagedElement. An example "
          "is where a metric value belongs to a combination of "
          "elements, such as the input and output ports of the traffic "
          "in a switch. If there are multiple ManagedElements "
          "associated with the metric value, then usually there is one "
          "that naturally belongs to the metric value and that one "
          "should be used to create the supplemental information. The "
          "property is not meant to be used as a foreign key to search "
          "on the measured element. Instead, the association "
          "to the ManagedElement should be used.") ]
   string MeasuredElementName;

      [Description (
          "Identifies the time when the value of a metric instance is "
          "computed. Note that this is different from the time when the "
          "instance is created. For a given CIM_BaseMetricValue instance, "
          "the TimeStamp changes whenever a new measurement snapshot "
          "is taken if Volatile is true. A managmenet application may "
          "establish a time series of metric data by retrieving the "
          "instances of CIM_BaseMetricValue and sorting them " 
          "according to their TimeStamp.") ]
   datetime TimeStamp;

      [Description (
          "Property that represents the time duration over which this "
          "metric value is valid. This property should not exist for "
          "timestamps that apply only to a point in time but should be "
          "defined for values that are considered valid for a certain "
          "time period (ex. sampling). If the \"Duration\" property "
          "exists and is nonNull, the TimeStamp is to be considered "
          "the end of the interval.") ]
   datetime Duration;

      [Required, Description (
          "The value of the metric represented as a string. Its "
          "original data type is specified in "
          "CIM_BaseMetricDefinition.") ]
   string MetricValue;

      [Description (
          "If present, specifies one BreakdownDimension from the "
          "BreakdownDimensions array defined in the associated CIM_"
          "BaseMetricDefinition. This is the dimension along which "
          "this set of metric values is broken down. For a description "
          "of the concept, see the class CIM_BaseMetricDefinition.") ]
    string BreakdownDimension;

      [Description (
          "Defines a value of the BreakdownDimension property defined "
          "for this metric value instance. For instance, if the "
          "BreakdownDimension is \"TransactionName\", this property "
          "could name the actual transaction to which this particular "
          "metric value applies.") ]
    string BreakdownValue;

      [Description (
          "If true, Volatile indicates that the value for the next "
          "point in time may use the same object and just change its "
          "properties (such as the value or timestamp). If false, the "
          "existing objects remain unchanged and a new object is "
          "created for the new point in time.") ]
    boolean Volatile;
};


// ===================================================================
// MetricInstance
// ===================================================================
      [Association, Version("2.7.0"), Description (   
        "Weak association of metric value objects with their metric "
        "definition. This association ties an instance of "
        "CIM_BaseMetricValue to its CIM_BaseMetricDefinition; it is weak "
        "because the existence of a CIM_BaseMetricValue depends on the "
        "existence of its associated CIM_BaseMetricDefinition: An "
        "instance of CIM_BaseMetricValue must not exist without being "
        "associated to its corresponding CIM_BaseMetricDefinition.") ]
class CIM_MetricInstance : CIM_Dependency {
  
      [Override ("Antecedent"), 
       Min (1), Max (1),
       Description (
          "The CIM_BaseMetricDefinition for this particular "
          "CIM_BaseMetricValue.") ]
    CIM_BaseMetricDefinition REF Antecedent;

      [Override ("Dependent"), Description (
          "A CIM_BaseMetricValue instance holding the Value.") ]
    CIM_BaseMetricValue REF Dependent;
};


// ===================================================================
// MetricDefForME
// ===================================================================
      [Association, Version("2.7.0"), Description (   
        "This association ties a CIM_BaseMetricDefinition to a "
        "CIM_ManagedElement to define metrics for the latter. The "
        "metrics definition is given context by the ManagedElement, "
        "which is why the definition is dependent on the element.") ]
class CIM_MetricDefForME : CIM_Dependency {
  
      [Override ("Antecedent"), 
       Description (
          "The CIM_ManagedElement that can have metrics of this type "
          "associated with it.") ]
    CIM_ManagedElement REF Antecedent;

      [Override ("Dependent"), 
       Description (
          "A CIM_BaseMetricDefinition for a CIM_ManagedElement.") ]
    CIM_BaseMetricDefinition REF Dependent;
};


// ===================================================================
// MetricForME
// ===================================================================
      [Association, Version("2.7.0"), Description (   
        "This association links a ManagedElement to the metric "
        "values being maintained for it.") ]
class CIM_MetricForME : CIM_Dependency {
  
      [Override ("Antecedent"),
       Description (
          "ManagedElement to which the metric values belong.") ]
    CIM_ManagedElement REF Antecedent;

      [Override ("Dependent"),
       Description (
         "A metric value for the ManagedElement.") ]
    CIM_BaseMetricValue REF Dependent;
};


// ==================================================================
// end of file
// ==================================================================
