Create or Extend Metric Families

If an out-of-the-box metric family does not fit your monitoring needs, extend an existing metric family or create a custom metric family. If an existing metric family is close to what you need, extend that metric family. If you need something new, create a custom metric family. For an example, see . 
capm310
HID_Create_or_Extend_Metric_Families
If an out-of-the-box metric family does not fit your monitoring needs, extend an existing metric family or create a custom metric family. If an existing metric family is close to what you need, extend that metric family. If you need something new, create a custom metric family. For an example, see Add a New Metric to an Existing Metric Family
Use the following procedures to create, extend, or update metric families:
To avoid possible data loss, always back up the certification directory anytime you extend, create, or update a metric family.
Create a Metric Family XML Template
For a new metric family, use an existing metric family to create an XML template. For an extension, get the XML for the target metric family.
To retrieve the name of the metric family in the UI, go to the Metric Families page. Click the downward arrow on any column, hover over
Columns
, and click
Internal Name
.
 
Follow these steps:
  1. Set up a REST client with a connection to the Data Aggregator server.
  2. Enter the following URL to retrieve the template metric family:
    • New Metric Family:
      http://
      da_hostname
      :8581/typecatalog/metricfamilies/
      mf_name
    • Extension:
      http://
      da_hostname
      :8581/typecatalog/metricfamilies/
      mf_name
      mf_name
      specifies the name of the template metric family.
  3. Select GET in the Method tab, and run the method.
    The REST client returns the XML information for the metric family.
    Use the XML as a template to create the custom or extended metric family.
Edit the Metric Family XML
To apply the necessary changes to the metric family, edit the XML file. For complete information about the XML structure, see Metric Family XML Structure.
If the Units attribute is not defined in the XML, the units label on reports is 'Units'.
When you extend a metric family, include only the XML nodes that require changes.
Import the Metric Family XML
To import the metric family, use a REST client.
Do not use the Import button in the CA
Performance Center
UI to import a metric family. This button only imports metric families in the genericWS format, which is outdated.
Follow these steps:
  1. Specify one of the following URLs:
    • Custom Metric Family:
      http://
      da_hostname
      :8581/typecatalog/metricfamilies/
    • Extend Metric Family:
      http://
      da_hostname
      :8581/typecatalog/metricfamilies/extension/
      mf_name
  2. On the
    Method
    tab, Select
    POST
    for a new custom metric family, or select
    PUT
    to update or extend a metric family.
  3. In the
    Body
    settings, select 'application/xml' as the 'Body Content-type'.
    Failing to set the Content-type results in a 415 error.
  4. Copy the metric family XML into the
    Body
    tab.
    Run the method.
    Your custom metric family is imported. If no errors occur, the Status field in the HTTP Response section displays the following result:
    HTTP/1.1 200 OK
Update Metric Family Properties
To change attributes, such as the display name, update the metric family properties.
Follow these steps:
  1. Specify the following URL:
    • Extend Metric Family: 
      http://
      da_hostname
      :8581/typecatalog/metricfamilies/extension/
      mf_name
  2. On the 
    Method
     tab, select 
    PUT
     to update or extend a metric family.
  3. In the 
    Body
     settings, select 
    application/properties
    as the
    Body Content-type
    .
  4. Specify updates with one line per property in the
    Body
    tab as illustrated in the following template and example.
    Template: 
    The
    metricfamilyname
    and
    attributename
    variables in the following example are case-sensitive and are lowercase. These variables are a different case from their values in the XML. For example,
    NormalizedPortInfo
    from the XML is
    normalizedportinfo
    here and
    PctDiscardsIn
    in the XML is
    pctdiscardsin
    here.
     
    im.ca.com.normalizer.
    metricfamilyname
    .displayname=DisplayName
    im.ca.com.normalizer.
    metricfamilyname
    .documentation=Documentation text
    im.ca.com.normalizer.
    metricfamilyname
    .attribute.
    attributename
    .attributedisplayname=AttributeDisplayName
    im.ca.com.normalizer.
    metricfamilyname
    .attribute.
    attributename
    .documentation=Documentation text
     
    Example:
    im.ca.com.normalizer.normalizedportinfo.displayname=Interface
    im.ca.com.normalizer.normalizedportinfo.documentation=Defines the identification information, configuration information, and polled metrics for interfaces.
    im.ca.com.normalizer.normalizedportinfo.attribute.pctdiscardsin.attributedisplayname=Percent Discards In
    im.ca.com.normalizer.normalizedportinfo.attribute.pctdiscardsin.documentation=The percentage of the frames (packets) received by the interface that were discarded.
  5. Run the method.
Trigger Rediscovery
After you extend a metric family, the changes occur during the nightly automatic rediscovery. If the changes do not apply automatically, trigger the update manually.
To avoid a severe impact on performance, do not trigger a rediscovery during normal business hours.
Follow these steps:
  1. Navigate to the
    Data Aggregator
    data source.
  2. Click
    Monitoring Configuration
    ,
    Metric Families
    .
  3. Select the metric family.
  4. Click
    Update Metric Family
    .
    The Data Aggregator rediscovers components on all devices that support the selected metric family.
Verify the Metric Family Results
To ensure successful operation, verify the results of the import.
Follow these steps:
  1. Log in to the UI, and navigate to the Data Aggregator data source.
  2. Go to Monitoring Configuration, Metric Families.
  3. Verify that the metric family in the list and that the Last Modified time has been updated.