Metric Family XML Structure

A metric family uses XML to define the set of metrics to collect and report on for a given technology. These metrics are normalized so that reporting is uniform regardless of the vendor (data source). Metrics are "null" when the vendor does not provide a value. Any report views based on the null metrics are empty.
capm360
HID_Metric_Family_XML_Structure
A metric family uses XML to define the set of metrics to collect and report on for a given technology. These metrics are normalized so that reporting is uniform regardless of the vendor (data source). Metrics are "null" when the vendor does not provide a value. Any report views based on the null metrics are empty.
A metric family also defines attributes that are captured during discovery, like the item name and index. There can also be discovery rules defined that reconcile component matching. You include a metric family in a monitoring profile. The set of metric families in a monitoring profile determines which metrics to collect for the devices in each device collection that is associated with the profile.
When you extend a metric family, do not edit restricted tabs or attributes. For more information, see Restricted XML Tags.
You must list some properties in the XML in a particular order. The properties included in the XML example and listed in the following descriptions are presented in the recommended order.
2
Example:
This example metric family supports the vendor certification for Frame-Relay PVC:
If you view the metric family XML in a browser, certain tags are hidden. For this reason, copy and paste the metric family XML only from a REST client
<?xml version="1.0" encoding="UTF-8" ?> 
<!-- Auto-generated by the type catalog local manager.  --> 
<DataModel xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance namespace="http://im.ca.com/normalizer" xsi:noNamespaceSchemaLocation="IMDBCertificationFacet.xsd">
  <Author>Custom</Author>
  <Version>1.0</Version>
  <FacetType name="frPVCInfo" descriptorClass="com.ca.im.core.datamodel.certs.NormalizedFacetDescriptorImpl">
    <Documentation>Frame Relay Permanent Virtual Circuit</Documentation> 
    <FacetOf namespace="http://im.ca.com/core" name="Item" /> 
    <DisplayName>Frame Relay PVC</DisplayName>
    <TableName>FR_PVC_INFO</TableName>
    <Protocol>IMDB</Protocol>
    <Normalized>true</Normalized> 
    <ComponentFacets>
         <Facet>{http://im.ca.com/inventory}frPVC</Facet> 
    </ComponentFacets>
    <AttributeGroup name="AttributeGroup" external="true" list="true">
      <Documentation /> 
      <Attribute name="Indexes" type="ObjectID[]">
         <Documentation />
         <AttributeDisplayName />
         <Polled>false</Polled> 
         <Baseline>false</Baseline> 
         <IsDbColumn>false</IsDbColumn> 
         <Variance>false</Variance> 
         <StandardDeviation>false</StandardDeviation> 
         <Minimum>false</Minimum> 
         <Maximum>false</Maximum> 
         <WriteOnPoll>false</WriteOnPoll> 
         <RollupStrategy />
         <Percentile>0</Percentile> 
       </Attribute>
       <Attribute name="Names" type="String">
         <Documentation>The name of the frame relay circuit</Documentation> 
         <AttributeDisplayName />
         <Polled>false</Polled> 
         <Baseline>false</Baseline> 
         <IsDbColumn>false</IsDbColumn> 
         <Variance>false</Variance> 
         <StandardDeviation>false</StandardDeviation> 
         <Minimum>false</Minimum> 
         <Maximum>false</Maximum> 
         <WriteOnPoll>false</WriteOnPoll> 
         <RollupStrategy /> 
         <Percentile>0</Percentile> 
        </Attribute>
        <Attribute name="Description" type="String">
          <Documentation>A description for the frame relay circuit</Documentation> 
          <AttributeDisplayName />
          <Polled>false</Polled> 
          <Baseline>false</Baseline> 
          <IsDbColumn>false</IsDbColumn> 
          <Variance>false</Variance> 
          <StandardDeviation>false</StandardDeviation> 
          <Minimum>false</Minimum> 
          <Maximum>false</Maximum> 
          <WriteOnPoll>false</WriteOnPoll> 
          <RollupStrategy />  
          <Percentile>0</Percentile> 
        </Attribute>
        <Attribute name="BECNIn" type="Double">
          <Documentation>Backward congestion since the virtual circuit was created</Documentation> 
          <AttributeDisplayName />
          <Polled>true</Polled> 
          <Baseline>false</Baseline> 
          <IsDbColumn>true</IsDbColumn> 
          <Variance>false</Variance> 
          <StandardDeviation>false</StandardDeviation> 
          <Minimum>false</Minimum> 
          <Maximum>false</Maximum> 
          <WriteOnPoll>false</WriteOnPoll> 
          <RollupStrategy>Sum</RollupStrategy> 
          <Percentile>0</Percentile> 
        </Attribute>
        <Attribute name="FECNIn" type="Double">
          <Documentation>Forward congestion since the virtual circuit was created</Documentation> 
          <AttributeDisplayName />
          <Polled>true</Polled> 
          <Baseline>false</Baseline> 
          <IsDbColumn>true</IsDbColumn> 
          <Variance>false</Variance> 
          <StandardDeviation>false</StandardDeviation> 
          <Minimum>false</Minimum> 
          <Maximum>false</Maximum> 
          <WriteOnPoll>false</WriteOnPoll> 
          <RollupStrategy>Sum</RollupStrategy>  
          <Percentile>0</Percentile> 
        </Attribute>
        <Attribute name="FramesIn" type="Double">
          <Documentation>Frames received since the virtual circuit was created</Documentation> 
          <AttributeDisplayName />
          <Polled>true</Polled> 
          <Baseline>false</Baseline> 
          <IsDbColumn>true</IsDbColumn> 
          <Variance>false</Variance> 
          <StandardDeviation>false</StandardDeviation> 
          <Minimum>false</Minimum> 
          <Maximum>false</Maximum> 
          <WriteOnPoll>false</WriteOnPoll> 
          <RollupStrategy>Sum</RollupStrategy> 
          <Percentile>0</Percentile> 
        </Attribute>
        <Attribute name="FramesOut" type="Double">
          <Documentation>Frames sent since the virtual circuit was created</Documentation> 
          <AttributeDisplayName />
          <Polled>true</Polled> 
          <Baseline>false</Baseline> 
          <IsDbColumn>true</IsDbColumn> 
          <Variance>false</Variance> 
          <StandardDeviation>false</StandardDeviation> 
          <Minimum>false</Minimum> 
          <Maximum>false</Maximum> 
          <WriteOnPoll>false</WriteOnPoll> 
          <RollupStrategy>Sum</RollupStrategy> 
          <Percentile>0</Percentile> 
        </Attribute>
        <Attribute name="BytesIn" type="Double">
          <Documentation>Bytes received since the virtual circuit was created</Documentation> 
          <AttributeDisplayName />
          <Polled>true</Polled> 
          <Baseline>false</Baseline> 
          <IsDbColumn>true</IsDbColumn> 
          <Variance>false</Variance> 
          <StandardDeviation>false</StandardDeviation> 
          <Minimum>false</Minimum> 
          <Maximum>false</Maximum> 
          <WriteOnPoll>false</WriteOnPoll> 
          <RollupStrategy>Sum</RollupStrategy> 
          <Percentile>0</Percentile> 
        </Attribute>
        <Attribute name="BytesOut" type="Double">
          <Documentation>Bytes sent since the virtual circuit was created</Documentation> 
          <AttributeDisplayName />
          <Polled>true</Polled> 
          <Baseline>false</Baseline> 
          <IsDbColumn>true</IsDbColumn> 
          <Variance>false</Variance> 
          <StandardDeviation>false</StandardDeviation> 
          <Minimum>false</Minimum> 
          <Maximum>false</Maximum> 
          <WriteOnPoll>false</WriteOnPoll> 
          <RollupStrategy>Sum</RollupStrategy> 
          <Percentile>0</Percentile> 
        </Attribute>
      </AttributeGroup>
      <Attribute name="SourceFacetTypes" cached="true" list="true" persistent="true" type="QName">
        <Documentation /> 
      </Attribute>
      <Expressions>
        <ExpressionGroup destCert="{http://im.ca.com/core}Item">
          <Expression destAttr="Name">Names</Expression> 
        </ExpressionGroup>
        <ExpressionGroup destCert="{http://im.ca.com/inventory}DeviceComponent">
          <Expression destAttr="IndexList">Indexes</Expression> 
        </ExpressionGroup>
      </Expressions>       
  </FacetType>
</DataModel>
Basic Properties
The basic properties of your custom metric family help to distinguish it from other custom metric families you create.
Consider the following restrictions when you determine basic properties:
  • The FacetType/name, DisplayName, and TableName
    properties must be unique for each metric family.
  • The Protocol tag is always IMDB.
  • The Normalized tag is always true.
  • Set the FacetType/descriptorClass property and all DataModel
    and FacetOf
    properties.
The following list details basic metric properties:
: Unless stated otherwise, all entries in this list can be updated.
  • FacetType/name
    Specifies the metric family name. For each metric family, the name must be a unique name that identifies it internally within the system. Carefully select a name with a minimal possibility of naming conflicts with future similar metric families. For example, define a naming scheme that ensures that these metric family names are unique.
    This name is never exposed externally. To display a metric family name in the user interface, use the DisplayName
    element.
    Can be updated:
    No
    Possible values:
    Alphanumeric and underscore. Dot and dash are not permitted. The value must be unique across all metric families.
  • Documentation
    Specifies the external description for the metric family. To make these comments useful, describe why and when you added or changed the metric family.
    Possible values:
     Plain text
    Effect of updating:
     None
     This property should be listed first under the
    FacetType/name
    .
  • FacetOf
    Asserts that this metric family is an item.
    Possible values:
     namespace="http://im.ca.com/core" name="Item"
  • DisplayName
    Specifies the metric family name that displays in the user interface.
    Possible values:
    Plain text
    Ensure that the DisplayName property is unique to the metric family.
    Effect of updating:
    Change to the name in the administrator user interface.
    When does the update take effect:
    Immediately
    Required actions for updates to take effect:
    Refresh the user interface.
     This property should be listed before the
    AttributeGroup
    property.
  • TableName
    Specifies the database table name that is used to store the metrics that the metric family collects.
    Possible values:
    Uppercase alphanumeric and underscore. The value must begin with a letter. The value must be unique across all metric families.
    Example: PROCESS_STATS
    Effect of updating:
    Poll data is stored in a new set of database tables.
    When you update the
    TableName, the old poll data is lost. Old report views are broken.
    When does the update take effect:
    Immediately. Before new views can be created, there is a delay of up to 5 minutes while
    CA Performance Management
     loads the new MIB files.
    Required actions for updates to take effect:
    Views must be recreated.
  • Protocol
    The Protocol tag is always IMDB.
  • Normalized
    The Normalized tag is always true.
  • SupportsDeviceAggregation
    Supports thresholding at the device level for some metrics.
    This attribute is not supported for custom or extended certification.
ComponentFacets
The ComponentsFacets section lists the facets that are created during discovery. Discovery identifies items as device components or creates a hierarchy relationship between items.
  • Facet
    Specifies a facet that is attached to the component item during component discovery.
    Can be updated:
    Yes
    Possible values:
    QName
    of the facet
    Effect of updating:
    If the component facet is synchronized to CA
    Performance Center
    , the component is visible in CA
    Performance Center
    .
    When does the update take effect:
    Rediscover
    Required actions for updates to take effect:
    Delete the device and rediscover.
ItemFacets
ItemFacets is a new section that will likely change to support future, complex metric family structures. Its use is discouraged.
ItemFacets
lists the facets that are created during discovery that identify items as devices.
  • Facet
    Specifies a facet that is attached to the item during discovery.
    Can be updated:
    Yes
    Possible values:
    QName
    of the facet
    Effect of updating:
    Component is visible on the REST service for the specified facet. If the component facet is synchronized to CA
    Performance Center
    , the component is visible in CA
    Performance Center
    .
    When does the update take effect:
    Rediscover
    Required actions for updates to take effect:
    Delete the device and rediscover.
Example:
<ItemFacets>
   <Facet>{http://im.ca.com/inventory}Host</Facet>
   <Facet>{http://im.ca.com/inventory}Device</Facet>
   <Facet>{http://im.ca.com/inventory}ConsolidatedAndDiscoveredMetricFamilyHistory</Facet>
   <Facet>{http://im.ca.com/core}Syncable</Facet>
   <!-- The IPDomainID attribute will be filled in by discovery  -->
   <Facet>{http://im.ca.com/core}IPDomainMember</Facet>
</ItemFacets>
AttributeGroup (Metric Family)
An AttributeGroup
is a collection of item discovery attributes and metric attributes. The item discovery attributes are set during discovery, like item descriptions. The metric attributes are collected during polling. The following information describes the elements that you use in the AttributeGroup
section.
Set the AttributeGroup/list and AttributeGroup/external properties to true. These properties specify that each attribute represents a list of values that is obtained from an external source. Customize the following XML elements:
All entries in this list can be updated using plain text. The update has no behaviorial impact.
  • AttributeGroup/name
    Specifies the attribute group name. Conform to the "<FacetType/name>Group" naming scheme.
  • Documentation
    (Optional) Specifies the description for the attribute group.
General Attributes (Metric Family)
The general attributes for all metric families are as follows:
All entries in this list can be updated. Unless specified otherwise, the update takes effect immediately and no actions are required to trigger the update. 
  • Attribute/name
    Specifies the unique, internal name. For metrics, this name is also used for naming the database column.
    This name is never exposed externally. To display an attribute name in the user interface, use the AttributeDisplayName
    element. To change the AttributeDisplayName, see Create or Extend Metric Families and update the metric family properties.
    Possible values:
    Alphanumeric and underscore.
    Effect of updating:
    For metrics, the values for this attribute are stored in a new database column corresponding to the updated name. The user loses the historical data that is collected for this metric (with the older name). The custom reports reporting on this metric fails.
    When does the update take effect:
    Next poll
    Required actions for updates to take effect:
    None
  • Attribute/type
    Indicates the data type of this attribute. The most frequently used data types are Int, Long, Double, String, or ObjectID. The database stores metric attributes as a float. Therefore, these attributes must use a numeric type (we recommend a Double). Other types are used for item attributes.
    Possible values:
    Boolean, Int, Long, Double (floating-point), BigInteger, String, DateTime, IPAddress, MACaddress, IPSubnet, OctetString (hex representation), ObjectID, ItemID, QName (Qualified Name)
    The type names are case insensitive, for example, "boolean" is the same as Boolean.
    Effect of updating:
    For metrics, none. All metrics are stored in the database as a float. For item attributes, the device must be deleted and rediscovered.
    When does the update take effect:
    For metrics, next poll. For item attributes, on rediscover.
    Required actions for updates to take effect:
    For metrics, none. For item attributes, delete the device and rediscover.
  • Documentation
    Displays the attribute description in the user interface. The documentation is also displayed in tool tips when you hover the cursor over the attribute name.
    Possible values:
     Plain text
    Effect of updating:
     Hovering the cursor over the attribute name shows the updated documentation.
     This property should be listed first under the
    Attribute/name
    and
    Attribute/type
    . This property and the
    AttributeDisplayName
    property must be listed before the other attribute properties in the XML.
  • AttributeDisplayName
    Specifies the name of the attribute in the UI. To change the AttributeDisplayName, see Create or Extend Metric Families and update the metric family properties.
    Possible values:
    Alphanumeric, space, and underscore.
    Effect of updating:
    The metric reflects the updated AttributeDisplayName in the Metric Families UI and custom reports.
     This property and the
    Documentation
    property must be listed before the other attribute properties in the XML.
  • AttributeAbbreviation
    This parameter is not supported.
  • Polled
    Indicates whether the attribute is polled. If it is set to false, it is only accessed during discovery.
    Possible values:
    true, false
    Effect of updating:
    If set to false, the OIDs corresponding to this attribute/metric are not polled when no other polled attribute/metric is using that OID in its expression. If set to true, the OIDs corresponding to this attribute/metric are polled.
    When does the update take effect:
    Next poll
    Required actions for updates to take effect:
    None
  • IsDbColumn
    Stores its value in the database table. IsDbColumn is used for metric attributes. Set the IsDbColumn value to true when Polled
    is set to true.
    Possible values:
    true, false
    Effect of updating:
    If set to false, the data for this attribute/metric is not stored in the database. If set to true, the data for this attribute/metric is stored in the database.
Discovery Attributes
For many attributes only the value that is retrieved during discovery is stored in the database. No further polling or processing, such as an evaluation of a baseline, is performed.
The Indexes and Names attributes must exist for all metric families. The Descriptions attribute is optional.
<Attribute name="Indexes" type="ObjectID[]"  />
<Attribute name="Names" type="String"  />
<Attribute name="Descriptions" type="String"  />
The metric families supporting Hierarchy must include these attributes:
<Attribute name="ItemUniqueIDs" type="String" />
<Attribute name="ParentUniqueIDs" type="String" />
Polled and Baseline Attributes
The following information describes the polled and baseline attribute elements:
All entries in this list can be updated.
  • Baseline
    Indicates whether to calculate a mean value for this attribute. If it is set to true, a corresponding BaselineList
    definition must be defined.
    The Baseline
    attribute requires that the StandardDeviation
    attribute is set to true.
    Possible values:
    true, false
    Effect of updating:
    Baseline values are calculated when true.
    When does the update take effect:
    Next poll
    Required actions for updates to take effect:
    None
  • Maximum
    Indicates whether to calculate the maximum of this attribute during the rollup. Creates a 'max_' column in the database table. If RollupStrategy is defined, this attribute must also be defined.
    Possible values:
    true, false
    Effect of updating:
    True provides a calculation of, and a reporting field for, “Maximum.”
    When does the update take effect:
    Next poll
    Required actions for updates to take effect:
    None
  • Minimum
    Indicates whether to calculate the minimum of this attribute during the rollup. Creates a 'min_' column in the database table. If RollupStrategy is defined, this attribute must also be defined.
    Possible values:
    true, false
    Effect of updating:
    True provides a calculation of, and a reporting field for, “Minimum.”
    When does the update take effect:
    Next poll
    Required actions for updates to take effect:
    None
  • StandardDeviation
    Indicates whether to calculate the standard deviation of this attribute during the rollup. Creates a 'std_' column in the database table. If RollupStrategy is defined, this attribute must also be defined.
    Possible values:
    true, false
    Effect of updating:
    True provides a calculation of, and a reporting field for, “Standard Deviation.”
    When does the update take effect:
    Next poll
    Required actions for updates to take effect:
    None
  • DeviationFromBaseline
    Requires that the Baseline attribute is set to true. Provides two extra reporting fields, “Average Baseline” and “Percent Deviation,” calculated using baseline data. These fields are not available for building custom views. No changes are made to the database table.
    Possible values:
    true, false
    Effect of updating:
    True provides the “Average Baseline” and “Percent Deviation” fields for the internal report development.
    When does the update take effect:
    Immediately
    Required actions for updates to take effect:
    None
  • Percentile
    Indicates whether to calculate the 95th percentile of this attribute during the rollup. Creates a 'pct_' column in the database table. If RollupStrategy is defined, this attribute must also be defined.
    Possible values:
    0, 95
    Effect of updating:
    A value of 95 provides a calculation of, and a reporting field for, “95th Percentile.” Zero specifies that no calculation is performed, and the reporting field is not available.
    When does the update take effect:
    Next poll
    Required actions for updates to take effect:
    None
  • Percentile2
    (Optional) Specifies the value of a user-configurable percentile.
    Possible values:
    0-99
    Effect of updating:
    A non-zero value specifies the percentile to calculate. Zero specifies that no calculation is performed, and the reporting field is not available.
    When does the update take effect:
    Next poll
    Required actions for updates to take effect:
    None
  • Percentile3
    (Optional) Specifies the value of a user-configurable percentile.
    Possible values:
    0-99
    Effect of updating:
    A non-zero value specifies the percentile to calculate. Zero specifies that no calculation is performed, and the reporting field is not available.
    When does the update take effect:
    Next poll
    Required actions for updates to take effect:
    None
    You cannot set two percentiles to the same non-zero value. You cannot set Percentile2 or Percentile3 to 95.
    Changes to
    Percentile2
    and
    Percentile3
    may cause discontinuity in the trend view depending on the time range.
  • ProjectionPercentile
    (Optional) Specifies the percentile to calculate for metric projection.
    Possible values:
    0-99
    Effect of updating:
    Changes the percentile to use to calculate projections. Zero specifies that no calculation is performed.
    Changes to
    ProjectionPercentile
    cause inaccurate projections for up to 90 days. When you change the value of
    ProjectionPercentile
    , the percentile values for days before the change are not recalculated.
    When does the update take effect:
    Next poll
    Required actions for updates to take effect:
    None
  • AggregateToDevice
    Supports thresholding at the device level for some metrics.
    This attribute is not supported for custom or extended certification.
  • RollupStrategy
    Specifies the operation that is performed every cycle during the rollup of the individually polled values. When Polled
    and IsDbColumn
    are set to true, this element is required.
    Possible values:
    Sum (a summation for counters), Avg (an average for gauges)
    Effect of updating:
    The specified strategy is used to perform rollup calculations.
    When does the update take effect:
    Next poll
    Required actions for updates to take effect:
    None
  • Rate
    Provides an extra reporting field, “Average Rate,” calculated as AVG (metric value / time). No changes are made to the database table.
    The Rate is available for reporting but not for use when monitoring the profile event rules.
    Possible values:
    true, false
    Effect of updating:
    Provides the “Average Rate” field for reporting.
    When does the update take effect:
    Immediately
    Required actions for updates to take effect:
    None
  • Units
    Specifies the name of the units label used in reports. The actual label that is displayed is translated according to the language setting of the report.
    If this attribute is not defined, the units labels on reports is 'Units'.
    Possible values:
    Percent, Packets, PacketsPerSecond, DiscardedPackets, ErroredPackets, Bits, BitsPerSecond, Bytes, BytesPerSecond, Seconds, Microseconds, Milliseconds, UnixTime, Observations, FramesPerSecond, Frames, RequestsPerSecond, Requests
    Effect of updating:
    The specified units label is displayed in reports.
    When does the update take effect:
    Immediately
    Required actions for updates to take effect:
    None
Example: Using polled and baseline attribute elements
<Attribute name="Utilization" type="double">
   <AttributeDisplayName>Utilization</AttributeDisplayName>
   <IsDbColumn>true</IsDbColumn>
   <Baseline>true</Baseline>
   <Minimum>true</Minimum>
   <Maximum>true</Maximum>
   <RollupStrategy>Avg</RollupStrategy>
   <StandardDeviation>true</StandardDeviation>
   <DeviationFromBaseline>true</DeviationFromBaseline>
   <Percentile>95</Percentile>
   <Polled>true</Polled>
   <Units>Percent</Units>
</Attribute>
SourceFacetTypes Attribute
SourceFacetTypes 
attribute is required for discovery and must be defined.
Use these required values:
  • Name: SourceFacetTypes
  • Type: QName
  • Cached: true
  • Persistent: true
  • List: true
Example:
 <Attribute name="SourceFacetTypes" type="QName" cached="true" persistent="true" list="true" />
Can be updated:
 No
Expressions
The Expressions section is composed of ExpressionGroup tags that are used for component discovery. During the component discovery, the values for the component item properties (such as the IndexList, Name, and Description) are calculated. The vendor certification expressions supporting the metric family expressions are used for this calculation.
Do not confuse the metric family and vendor certification ExpressionGroup tags.
The ExpressionGroup tags for the following DestCert URIs must exist:
DestCert
DestAttr
{http://im.ca.com/core}Item
Name
{http://im.ca.com/core}Item
Description
{http://im.ca.com/inventory} DeviceComponent
IndexList
All entries in this list can be updated.
  • ExpressionGroup/name
    (Optional) Specifies the expression group name.
    Possible values:
    Plain text
    Effect of updating:
    None
  • ExpressionGroup/destCert
    Specifies the component facet that contains the destAttrs to populate. The facet name typically comes from the ComponentFacets section, except the Item and DeviceComponent facets.
    Possible values:
    Facets that are defined in ComponentFacets, or the Item, DeviceComponent facet.
    Effect of updating:
    Changes permissible expression destAttr
    When does the update take effect:
    Component Rediscovery
    Required actions for updates to take effect:
    None
  • ExpressionGroup/Expression
    Specifies the expression for the component facet attribute.
    Possible values:
    Any valid metric
    Effect of updating:
    Changes permissible expression destAttr
    When does the update take effect:
    Component Rediscovery
    Required actions for updates to take effect:
    None
  • ExpressionGroup/Expression/destAttr
    Specifies the component facet attribute name.
    Possible values:
    Any valid attribute from that component facet.
    Effect of updating:
    Changes the attribute name
    When does the update take effect:
    Component Rediscovery
    Required actions for updates to take effect:
    None
Hierarchy
A hierarchy, or parent-child relationship, can be defined between items of different metric families, for example, Interface and CBQoS Classmap. In the metric family definitions, the Hierarchy must be specified in the child metric family with:
  • The Hierarchy QName in the ComponentFacets
  • The ItemUniqueID and ParentUniqueID destAttr values in the Hierarchy ExpressionGroup
  • The ItemUniqueIDs and ParentUniqueIDs attributes in the AttributeGroup
The supporting expressions are defined in the vendor certifications.
The Hierarchy ExpressionGroup tags for the following DestCert URIs must exist:
DestCert
DestAttr
{http://im.ca.com/inventory}Hierarchy
ItemUniqueID
{http://im.ca.com/inventory}Hierarchy
ParentUniqueID
Example:
<ComponentFacets>
   <Facet>{http://im.ca.com/inventory}QoSClassMap</Facet>
   <Facet>{http://im.ca.com/inventory}Hierarchy</Facet>
</ComponentFacets>
<ExpressionGroup name="Hierarchy" destCert="{http://im.ca.com/inventory}Hierarchy">
   <Expression destAttr="ItemUniqueID">ItemUniqueIDs</Expression>
   <Expression destAttr="ParentUniqueID">ParentUniqueIDs</Expression>
</ExpressionGroup>
<AttributeGroup name="QosCosGroup" list="true" external="true">
     <Attribute name="ItemUniqueIDs" type="String" />
     <Attribute name="ParentUniqueIDs" type="String" />     
     ...
</AttributeGroup>
BaselineDefinitions
The BaselineDefinitions
 
section contains the baseline definitions to calculate for this metric family. A baseline definition must be specified for each metric in the AttributeGroup
 
section whose Baseline
 
property is set to true.
You can define two types of baselines: Hourly (required) and Daily (optional). Hourly baselines are used both for event processing and for displaying baselines in reports. Daily baselines are used for displaying baselines in reports with a time frame of one month or greater.
The following information describes the baseline elements used:
  • Name
    Specifies the type of baseline definition for a metric. The type is either hourly or daily.
    Can be updated: 
    No
    Possible values:
     HourlyBaseline, DailyBaseline
  • ID
    Specifies a value that is no longer used. However, the field must be specified as a positive integer and must be unique across all hourly and daily baseline definitions within this metric family.
    Can be updated: 
    Yes
    Possible values: 
    Any unique and positive integer.
    Effect of updating:
     None
  • PerformanceMetric
    Specifies the name (case sensitive) of the metric for which the baseline is calculated. Set the Polled and Baseline properties for the metric attribute to true.
    Can be updated: 
    Yes
    Possible values:
     A valid metric name (case sensitive).
    Effect of updating:
     Baseline calculations are performed for the metric.
    When does the update take effect:
     Next baseline calculation, either hourly or daily.
    Required actions for updates to take effect:
     None
  • Period
    Specifies the type of baseline calculation, hourly or daily. Specify the value "1 Hour" for an HourlyBaseline Name or "1 Day” for a DailyBaseline Name.
    Can be updated:
     Yes
    Possible values:
     1 Hour, 1 Day
    Effect of updating:
     Baseline calculations are performed either hourly or daily.
    When does the update take effect: 
    Next baseline calculation, either hourly or daily
    Required actions for updates to take effect: 
    None
  • ProjectionInterval
    (Optional) Specifies the projection period in days for metric projection. Specify this expression in DailyBaseline.
    Can be updated:
     Yes
    Possible values:
     0 or any positive integer 
    Effect of updating:
     Changes the period that the system calculates projection values for. Zero specifies that no calculation is performed.
    When does the update take effect: 
    Next baseline calculation.
    Required actions for updates to take effect:
     PredicitionInterval requires that ProjectionPercentile is set to a non-zero value.
  • ProjectionInterval2
    (Optional) Defines a second projection interval. For details, see ProjectionInterval.
  • ProjectionInterval3
    (Optional) Defines a third projection interval. For details, see ProjectionInterval.
  • Window
    Specifies a value that is no longer used. However, the field must be specified as “30 Days” for hourly baselines and “90 Days” for daily baselines.
    Can be updated:
     No
    Possible values:
     30 Days, 90 Days
  • StartDate, EndDate, DaysOfWeek
    Specifies more values that are not used, but they must be specified as 0 (zero).
    Can be updated:
     No
    Possible values:
     0
ComponentReconciliation
The following information defines the component reconciliation logic that is used in component discovery. First, this information determines whether the system has already discovered this component or not. Then, the reconciliation logic determines whether to update an existing component or create a new one.
There can be multiple ordered algorithms per metric family. If a metric family does not define a reconciliation algorithm, a default one with match attribute Item.Name is applied.
ItemReconciliation
ItemReconciliation is a new section that will likely change to support future, complex metric family structures. Its use is discouraged.
The following information defines the item reconciliation logic that is used in item discovery. The logic determines whether the system has already discovered an item or not. Based on this determination, an existing item is updated or a new item is created. Item reconciliation is similar to component reconciliation. However, item reconciliation is used for items that are not components, such as virtual hosts. The ItemFacets are added to any new items or to any matching items (if the facets do not exist).
Example:
<ItemReconciliation>
   <SourceAgentScopedReconciliation>
    <MatchAlgorithms>
       <ExactMatch>
          <MatchAttribute name="{http://im.ca.com/inventory}SourceAgentInfo.SourceAgentIndexes" />
       </ExactMatch>
    </MatchAlgorithms>
   </SourceAgentScopedReconciliation>
   <GlobalScopedReconciliation matchDevices="true" />
</ItemReconciliation>
  • SourceAgentScopedReconciliation
    Defines the match algorithms that are used to reconcile items.
    Can be updated:
    Yes
    Effect of updating:
    Changes the item reconciliation logic.
    When does the update take effect:
    Rediscovery
    Required actions for updates to take effect:
    Update the metric family or change the vendor certification priority.
  • GlobalScopedReconciliation
    Defines the match algorithms that are used when items could not be reconciled for the source agent. The GlobalScopedReconciliation algorithms are used to locate items that have been created for other agents but match the potential new items. If the matchDevices property is set to true, the system default (built-in, not visible in XML) ComponentReconciliationInfo match algorithm is used. The match algorithm is based on the device primary IP address and host name.
    Can be updated:
    Yes
    Effect of updating:
    Changes the item reconciliation logic.
    When does the update take effect:
    Rediscovery
    Required actions for updates to take effect:
    Update the metric family or change the vendor certification priority.
MatchAlgorithms
Component reconciliation and item reconciliation use match algorithms. Two match algorithms are supported:
  • ExactMatch
    All specified attributes must be matched to say the item matches with the new data.
  • BestOfMatch
    Users must specify the least number of attributes to be matched by using the "leastMatchCount" value. Also, each attribute has a "required" key property. If the required property is set to true, that attribute must be matched to be considered a match.
The algorithm has a match precedence when multiple algorithms are provided for a metric family. The order of the algorithms determines the precedence. The algorithm at the top has the highest precedence. The bottom one has the lowest precedence.
Each algorithm must have at least one matching attribute. When data matches to multiple items with the same algorithm, the item with the most matched attributes wins. When multiple matched items have the same number of matched attributes, the winner is picked at random from these items.
Examples: How the reconciliation works
Two match algorithms are provided for a metric family: alg1 and alg2. Alg1 has higher precedence than alg2. The metric family has three existing component items: 1, 2 and 3. Rediscovering the metric family finds three entries: A, B, and C. Now, we apply the two algorithms to determine which entry is new, changed, and unchanged.
   Reconciliation Meta Data                   New Data          Existing Components
<ComponentReconciliation>                        A                    1
  <MatchAlgorithms>                              B                    2
    <MatchAlgorithm1>                            C                    3
      <MatchAttribute name="attr1"/>
      <MatchAttribute name="attr2"/>
    </MatchAlgorithm1>
    <MatchAlgorithm2>
      <MatchAttribute name="attr1"/>
      <MatchAttribute name="attr3"/>
      <MatchAttribute name="attr4"/>
    </MatchAlgorithm2>
  </MatchAlgorithms>
</ComponentReconciliation>
<MatchAlgorithm1> and <MatchAlgorithm2> can be either <ExactMatch> or <BestOfMatch>. The order of the two match algorithms tells us that MatchAlgorithm1 has a higher precedence than MatchAlgorithm2.
  • Case 1: Unique 1-to-1 Match
    Entry A matches to item 1, and item 1 does not have any other match.
    A -----> 1
    This example is the simplest case. This match is unique, so it does not matter if it also matches alg1 or alg2. Entry A matches item 1.
    A good match algorithm produces more unique matches.
  • Case 2: One entry has multiple matches
    Entry A matches to item 1 by alg1 and also matches to 2 by alg2.
               ---> 1 (alg1)  (1 wins)
          /
        A                    Since alg1 has higher precedence, item 1 wins the match.
          \
               ---> 2 (alg2)
  • Case 3: Multiple entries match to the same item with different algorithms
    Entry A matches to 1 by alg1 and entry B also matches to item 1 by alg2.
    A ------> 1 (alg1)  (A wins)
    B ------> 1 (alg2)
    Since alg1 has higher precedence, entry A wins.
  • Case 4: Multiple entries match to the same item with same algorithm but different numbers of matched attributes
    Both A and B match to 1 by alg1.
    A ------> 1 (alg1, # of matched attrs: 2)  (A wins)
    B ------> 1 (alg1, # of matched attrs: 1)
    Because A has more matched attributes, A wins.
    If the number of match attributes is the same, the winner is randomly picked and a warning is generated.
  • Case 5: Mixed match 1
     alg1
      A ------------------------------------> 1
        /  alg2(match attr count: 3)
      B
        \  alg2(match attr count: 2)
               --------------------------------> 2
    A matches to 1 because it matches with a higher precedence algorithm.
    B matches to 2 because 1 has matched to A.
  • Case 6: Mixed match 2
           ---------> 3 
        /  alg1
      A                ==> A wins 3 because alg1 has a higher matching precedence
        \  alg2
           ---------> 1
        /  alg2
      B                ==> B wins 2 because alg1 has a higher matching precedence
        \  alg1
           ---------> 2
        /  alg2
      C                   ==> C has no match because 2 is matched to B and 3 is matched to A
        \  alg2
           ---------> 3
    Entry C is treated as a new component. 1 is considered as an unmatched item.
    The more match case 1 (unique match), the better the match algorithm is.
    Can be updated:
    Yes
    Effect of updating:
    Changes the component reconciliation logic.
    When does the update take effect:
    Rediscovery
    Required actions for updates to take effect:
    Update metric family or change vendor certification priority.
ReconfigDetectionAttr
This element defines a metric family attribute that is used for change detection. You can enable the change detection on a monitoring profile. Data Aggregator polls that attribute only to verify whether the target device has changed, instead of doing a complete rediscovery. This feature helps performance and helps reduce the network traffic.
  • Can be updated:
    Yes
  • Possible values:
    The full name of the metric family attribute. The specified metric family attribute flag must have the cached, persistent, and external flags set to true.
  • Effect of updating:
    Change to component reconfiguration detection.
  • When does the update take effect:
    After rediscovery
  • Required actions for updates to take effect:
    Update metric family or change vendor certification priority.
Tags in Custom and Extended Metric Families
The following tags have restricted use in custom and extended metric families:
  • Variance
    The value of this tag must be 'false'.
  • RollupExpression
    Remove this tag or the value must be blank.
  • The Normalized tag is always true.