How to modify Response Path Component Element names in NetOps Portal

Products

CA Infrastructure Management CA Performance Management - Usage and Administration DX NetOps

Issue/Introduction

How can Response Path element names be modified at discovery run time?

In the out of the box NetOps Portal and Data Aggregator (DA) products, you can discover Response Path tests from devices for data collection and reporting. Using the default Monitoring Profiles (MP), their related Metric Families (MF) and Vendor Certifications (VC) for Response Path Component Element Discovery the names of the elements created in most cases will be:

<Source_IP_Address> - <Destination_IP_Address>: <Index_of_Test>

For example a Response test originating at the source device that resides at IP address 1.1.1.1, communicating with a destination device residing at IP address 2.2.2.2, with the test configured in the MIB at Index 100 the resulting Component Element name will be:

1.1.1.1 - 2.2.2.2: 100

Environment

Release: Any
Component: Data Aggregator

Resolution

Often such a name leaves users wanting more, such as an element name that provides easier identification showing what the test is doing, what its purpose is, or who the real source and destination device hosts are for the test. We can change the element names with some minor customization to the existing VC entries. There is no ability to modify the default out of the box VC entries. But we can export them to utilize as templates when creating custom VCs. This allows us to utilize the work done in the out of the box product, changing what is needed and reusing the rest of the VC XML code.

In this example, which can be applied to other similar VC data, we will use the 'Cisco IPSLA Jitter Precision Statistics’ default VC as the basis for our customization's. The high level steps involved in this task are:

Determine default VC to use as a template
Export it for editing
Edit the VC name so it is unique
Edit the Names Expression
Import the custom VC
Set the VC Priority and rediscover the elements to change names

Before beginning implementation of this change some considerations need to be reviewed.

What devices and their tests will be impacted by this change? If this change will target all Response Path Test Component Elements we can import the custom VC against the default MP and MF configurations, using the VC Priority list to place the custom VC at a higher priority than the default VC it replaces in the Vendor Certification Priority List order. This way it will be used first if matches are seen rather than the default, while leaving the default to pick up other Response tests that don't match the custom VC.

If this change is going to be limited to particular devices, some preparation is required.

Ensure the default Response Path MP is not linked to the target devices via the default Collections.
Ensure the target devices are in a custom Collection
Create a copy of the Response Path MP or create a custom new MP

After the custom VC is created, the custom MP it uses is then linked to the custom Collection created. With this being the only Response Path related MP linked to the target devices via their membership in a custom Collection, the custom VC changes will only apply to those devices and their related Component Elements.

NOTE: This solution will focus on applying this change to all devices

What is the target for the new names of the Response Path Component Elements?

This change requires the new names value be available to the Data Aggregator via the devices MIB data. We must have a specific MIB OID that is populated with the data used for the new names, to use in this solution. Data driven by other protocols or means outside of standard SNMP MIB data on the device will not work for this solution. This solution example assumes that the MIB OID used for the new name format is part of the already defined MIBs used by the default VC for Response Path Test Component Element creation and data collection.

As noted previously the default VC we'll focus on here is named:

Cisco IPSLA Jitter Precision Statistics

This VC is found associated to the default MF named:

Response Path Test Ethernet Jitter

This MF is found associated to the default MP named:

Response Path

Step 1: What VC will we use?

How do I know what VC to use for editing? This is fairly simple to determine. First we identify the parent device that hosts the element to be changed. Find that device in the DA views in the Inventory (not the NetOps Portal Inventory). When the device is selected, review the "Polled Metric Families" tab. Find the Metric Family and Vendor Certification entry that when selected shows the Component Elements that require a change. Not the VC name in the Vendor Cert column of the Polled Metric Families tab. That is what we'll search for in Step 2 below.

Step 2: Export the default Vendor Certification

Once we know the default VC we'll be using as a template, we need to find and export it via REST services for editing and import. First we need to list out all VC entries in the system to find the VC based on its Display Name (DisplayName attribute in XML). Then we can export the individual VC using its internal name (FactType name attribute value in XML).

To list out all VC entries known to the Data Aggregator (DA) we use this URL in a GET request via a REST Client:

http://<DA_HostName>:8581/typecatalog/certifications/snmp/

Insert your DA Host Name or IP address where <DA_HostName> is present.

We know the name of the VC in the UI so searching that we find this line in the XML from the REST GET

<DisplayName>Cisco IPSLA Jitter Precision Statistics</DisplayName>

That will reside in the rough 'middle' of the VC XML code. If we then scroll up to find the start of the VC it will look like this in this example:

<Documentation>Support for the particular table in the cisco-rttMon.mib MIB</Documentation>

We have now found our VC to be exported, and found the start of its entry (the "<FacetType name=" is the beginning of every VC), we need to find the end of the VC. The end of the VC will be the closing "</FacetType>" tag. In this case at the end of the ExpressionGroup entries we see:

</ExpressionGroup>

</Expressions>

</FacetType>

Having identified the full default VC XML code we need to modify, copy and paste it out of the REST client into a preferred text editor for modification.

An alternative to this is to now run this URL in a REST GET query:

http://<DA_HostName>:8581/typecatalog/certifications/snmp/CiscoIPSLAJitterPrecisionMib

By adding the FacetType name value, the internal name, we can pull out just that single VC. Advanced REST client users may find that useful for in place editing.

Step 3: Edit the VC name so it is unique

The values we need to edit to make a custom VC that is unique are:

<FacetType name="CiscoIPSLAJitterPrecisionMibCustom"

And:

<DisplayName>Cisco ICMP Jitter Precision Statistics</DisplayName>

FacetType is the internal name of the VC. It MUST be unique or the import will throw an error. It is a plain text value. Possible values:

Alphanumeric and underscore.
Dot and dash are not permitted.

DisplayName is the external name of the VC seen in the NetOps Portal. It is a plain text value. Possible values:

Alphanumeric, space, and underscore.

For example in this default VC the values out of the box are:

<FacetType name="CiscoIPSLAJitterPrecisionMib"

And:

<DisplayName>Cisco ICMP Jitter Precision Statistics</DisplayName>

If we are making this edit for a company named Acme Inc., the new values might be:

<FacetType name="CiscoIPSLAJitterPrecisionMibAcmeInc"

And:

<DisplayName>Cisco ICMP Jitter Precision Statistics for Acme Inc</DisplayName>

In another scenario maybe you are a Service Provider where this change targets a specific clients needs. If that client is named ABC Data you might set the values:

<FacetType name="CiscoIPSLAJitterPrecisionMibABCData"

And:

<DisplayName>Cisco ICMP Jitter Precision Statistics for ABC Data</DisplayName>

Step 4: Edit the Names expression

Here is where the meat of the task at hand occurs. This is where we'll edit the default Names expression, which defines how the Component Elements for this VC are named.

The VC lists expressions in its ExpressionGroup section, one of which is the Names expression. The default entry for this VC is:

<Expression destAttr="Names">"Cisco Rttmon Jitter Precision: " + (isdef(rttMonEchoAdminSourceAddress)?rttMonEchoAdminSourceAddress:"") + "-" + (isdef(rttMonEchoAdminTargetAddress)?rttMonEchoAdminTargetAddress:"") + " : " + JitterPrecisionStatsIndex</Expression>

What we see transpiring here is that when elements are created, this VC tells the system to set the name with the values of the rttMonEchoAdminSourceAddress, rttMonEchoAdminTargetAddress and JitterPrecisionStatsIndex MIB Objects. That is how we end up with the default naming scheme described above at the beginning of this article.

The method the VC uses to determine those MIB Object values is by looking up the definition of the given MIB Object in the Attribute section of the VC. We can see in this default VC those three MIB OID values are defined as:

</Attribute>

<IsKey>false</IsKey>

<NeedsDelta>false</NeedsDelta>

</Attribute>

<IsKey>false</IsKey>

<NeedsDelta>false</NeedsDelta>

</Attribute>

By these Attribute entries for each MIB Object it tells the VC and thus the environment what MIB Object ID to query for a value. I note this because when defining the new MIB OID to use in element naming we MUST add an Attribute entry defining the OID for it to be queried successfully.

In this example we are going to use the rttMonCtrlAdminTag MIB OID to populate element names. This assumes that this OID is populated with values in the device targeted for this change.

The new Names value using that MIB OID will be for this example:

<Expression destAttr="Names">"Cisco Rttmon Jitter Precision: "+ (isdef(rttMonCtrlAdminTag)?rttMonCtrlAdminTag:"") + " : " + JitterPrecisionStatsIndex</Expression>

When working correctly the new names for the elements will be:

rttMonCtrlAdminTag : Index

If the value for index 100 rttMonCtrlAdminTag is CA_IPSLA-Test1, the name of the element would become:

CA_IPSLA-Test1 : 100

Now that we've edited the Names expression, we need to add the rttMonCtrlAdminTag OID to the Attribute entries. In the Attribute Group entries of the VC add the OID definition. In this example it would be:

<IsKey>false</IsKey>

<NeedsDelta>false</NeedsDelta>

</Attribute>

Step 5: Import the custom VC

At this point we've exported the default VC, changed its FacetType name value, changed its DisplayName value, modified the Names attribute to edit element names and defined the new OID the elements names will be derived from. Now we need to import the custom VC into the system for use.

Earlier we copied out the default VC to use as a template, taking everything between the "<FacetType name=" opening XML tag, and the </FacetType> closing XML tag.

Before we can import this new custom VC we MUST be sure we add a few more details to the XML code to import. The start of every VC XML code to be imported MUST have this section at the top defining the "<DataModel" values.

<?xml version="1.0" encoding="UTF-8"?>

<DataModel namespace="http://im.ca.com/certifications/snmp"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="SNMPCertificationFacet.xsd">

As always an opened XML tag must have a closing tag somewhere. In this case the last line of the XML code being imported MUST have this closing tag.

</DataModel>

There can be NO edits made to this part of the XML code or errors will be seen in the REST client.

With those changes made, the top of the VC to be imported in this example would be:

<?xml version="1.0" encoding="UTF-8"?>

<DataModel namespace="http://im.ca.com/certifications/snmp"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="SNMPCertificationFacet.xsd">

<Documentation>Support for the particular table in the cisco-rttMon.mib MIB</Documentation>

And the end of the VC to be imported in this example would be:

</Expressions>

</FacetType>

</DataModel>

To import the custom VC, paste the content of the entire XML we've created here into a REST client and use the POST method to import it. Use this URL to import the VC:

http://<DA_HostName>:8581/typecatalog/certifications/snmp/

Success should be seen by the appearance of a message similar to "OK - 200" in the REST Client.

If a success message is returned validate the import did work by running a GET in the REST client against the same URL. Search it for the custom VCs new FacetType Name or DisplayName value. Find the newly imported custom VC and verify the changes made are correct.

Step 6: Modify VC Priority; Rediscover Component Elements to set new names

The last step in this process is to set the new custom VC to a Priority in the MF VC Priority List. Without taking this step the default VC will take precedence when it finds elements to create. To take this step find the MF that the VC was imported against through the DA Views in NetOps Portal. To do go to Admin->Data Sources and select the Data Aggregator. Under Monitoring Configuration select Metric Families. Find the one this custom VC was imported against and select it from the list. Now select the Vendor Certification Priorities tab. Choose the Manage button and set the custom VC at a higher priority than the default.

When done we have one last step to complete this task. We need to tell the system to rediscover the MF that was changed. This will happen naturally through the MPs Change Detection schedule but that could be up to 24 hours from the current time with default Change Detection schedules set. To accelerate the process find and select the device this change is being applied to in the DA Views Monitored Inventory listings. Select it and look in the Polled Metric Families tab to find the MF and VC that has been modified. Select the line (selecting the MF or VC name which is a link will load a different view) containing that entry. Now the "Update Metric Family" button should become available. Select it to run the MF discovery. When done the Component Element names should now be updated reflecting the new element naming scheme set in the custom VC imported.