// ===================================================================
// Title:  Base Metrics
// $State: Exp $
// $Date: 2004/08/15 05:55:36 $
// $Source: /cvsroot/wbemservices/open/mof/dmtf/2.9/Metrics_BaseMetric.mof,v $
// $Revision: 1.1 $
// ===================================================================
//#pragma inLine ("Includes/copyright.inc")
// Copyright 1998-2004 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.
//#pragma inLine
// ===================================================================
// 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.9 (Preliminary)
//     CR1296 - Add meta data properties to CIM_BaseMetricDefinition
//              that describe the Metric type and add
//              ModelCorrespondence to BaseMetricValue
// CIM 2.8 (Final) - None
// CIM 2.8 (Preliminary) - None
// 
// 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.8.1000" ), 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[];

      [Experimental, Description (
          "IsContinuous indicates whether or not the metric value is "
          "continuous or scalar. Performance metrics are an example of "
          "a linear metric. Examples of non-linear metrics include "
          "error codes or operational states. Continuous metrics can "
          "be compared using the \"greater than\" relation.")]
   boolean IsContinuous;

      [Experimental, Description (
          "ChangeType indicates how the metric value changes, in the "
          "form of typical combinations of finer grain attributes such "
          "as direction change, minimum and maximum values, and "
          "wrapping semantics. \n"
          "0=\"Unknown\": The metric designer did not qualify the "
          "ChangeType. \n"
          "2=\"N/A\": If the \"IsContinuous\" property is \"false\", "
          "ChangeType does not make sense and MUST be is set to "
          "\"N/A\". \n"
          "3=\"Counter\": The metric is a counter metric. These have "
          "non-negative integer values which increase monotonically "
          "until reaching the maximum representable number and then "
          "wrap around and start increasing from 0. Such counters, "
          "also known as rollover counters, can be used for instance "
          "to count the number of network errors or the number of "
          "transactions processed. The only way for a client "
          "application to keep track of wrap arounds is to retrieve "
          "the value of the counter in appropriately short intervals. "
          "\n4=\"Gauge\": The metric is a gauge metric. These have "
          "integer or float values that can increase and decrease "
          "arbitrarily. A gauge MUST NOT wrap when reaching the "
          "minimum or maximum representable number, instead, the value "
          "\"sticks\" at that number. Minimum or maximum values inside "
          "of the representable value range at which the metric value "
          "\"sticks\", may or may not be defined. \n"
          "Vendors may extend this property in the vendor reserved "
          "range."), 
       ValueMap { "0", "2", "3", "4", "5..32767", "32768..65535" }, 
       Values { "Unknown", "N/A", "Counter", "Gauge", "DMTF Reserved",
          "Vendor Reserved" }, 
       ModelCorrespondence { "CIM_BaseMetricDefinition.IsContinuous" }]
   uint16 ChangeType;

      [Experimental, Description (
          "TimeScope indicates the time scope to which the metric "
          "value applies. \n"
          "0=\"Unknown\" indicates the time scope was not qualified by "
          "the metric designer, or is unknown to the provider. \n"
          "2=\"Point\" indicates that the metric applies to a point in "
          "time. On the corresponding BaseMetricValue instances, "
          "TimeStamp specifies the point in time and Duration is "
          "always 0. \n"
          "3=\"Interval\" indicates that the metric applies to a time "
          "interval. On the corresponding BaseMetricValue instances, "
          "TimeStamp specifies the end of the time interval and "
          "Duration specifies its duration. \n"
          "4=\"StartupInterval\" indicates that the metric applies to "
          "a time interval that began at the startup of the measured "
          "resource (i.e. the ManagedElement associated by "
          "MetricDefForMe). On the corresponding BaseMetricValue "
          "instances, TimeStamp specifies the end of the time "
          "interval. If Duration is 0, this indicates that the startup "
          "time of the measured resource is unknown. Else, Duration "
          "specifies the duration between startup of the resource and "
          "TimeStamp."), 
       ValueMap { "0", "2", "3", "4", "5..32767", "32768..65535" }, 
       Values { "Unknown", "Point", "Interval", "StartupInterval",
          "DMTF Reserved", "Vendor Reserved" }, 
       ModelCorrespondence { "CIM_BaseMetricValue.TimeStamp",
          "CIM_BaseMetricValue.Duration" }]
   uint16 TimeScope;

      [Experimental, Description (
          "GatheringType indicates how the metric values are gathered "
          "by the underlying instrumentation. This allows the client "
          "application to choose the right metric for the purpose. \n"
          "0=\"Unknown\": Indicates that the GatheringType is not "
          "known. \n"
          "2=\"OnChange\": Indicates that the CIM metric values get "
          "updated immediately when the values inside of the measured "
          "resource change. The values of OnChange metrics truly "
          "reflect the current situation within the resource at any "
          "time. An example is the number of logged on users that gets "
          "updated immediately as users log on and off. \n"
          "3=\"Periodic\": Indicates that the CIM metric values get "
          "updated periodically. For instance, to a client "
          "application, a metric value applying to the current time "
          "will appear constant during each gathering interval, and "
          "then jumps to the new value at the end of each gathering "
          "interval. \n"
          "4=\"OnRequest\": Indicates that the CIM metric value is "
          "determined each time a client application reads it. The "
          "values of OnRequest metrics truly return the current "
          "situation within the resource if somebody asks for it. "
          "However, they do not change \"unobserved\", and therefore "
          "subscribing for value changes of OnRequest metrics is NOT "
          "RECOMMENDED."), 
       ValueMap { "0", "2", "3", "4", "5..32767", "32768..65535" }, 
       Values { "Unknown", "OnChange", "Periodic", "OnRequest",
          "DMTF Reserved", "Vendor Reserved" }]
   uint16 GatheringType;
};


// ==================================================================
// BaseMetricValue
// ==================================================================
   [Version ( "2.8.1000" ), 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;

      [Experimental, 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."), 
       ModelCorrespondence { "CIM_BaseMetricDefinition.TimeScope",
          "CIM_BaseMetricValue.Duration" }]
   datetime TimeStamp;

      [Experimental, 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."), 
       ModelCorrespondence { "CIM_BaseMetricDefinition.TimeScope",
          "CIM_BaseMetricValue.TimeStamp" }]
   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
// ==================================================================
