TMS DLA Best Practices
Note: The following work was done with the TMS DLA version for ITM 6.2.3 FP03.
The out-of-the-box configuration for the TMS DLA needs some improvements in order for the data to be useful when bulkloaded into TADDM. The following are some best practices for customizing the TMS DLA configuration files to generate more accurate IdML books.
Important Tips and Information
-
Make sure that you back up all template, jar, and script files before editing.
-
The DLA won't discover data for any agent unless there is a local OS agent running on that target system. If agentless/remote monitoring is set up for a target then the DLA will not discover it. This is is per the TMS DLA documentation.
-
Sample template files are provided as attachments to this wiki page. The templates contain the changes listed below. User assumes all risks involved in using these templates.
The default JVM heap size for the TMS DLA script is 256mb and this is much too low for most environments. When the heap is exhausted for one of the discover threads that will cause the thread to die and you will experience missing data in the IdML books. Edit tmsdla.sh, go near the bottom of the file and change the java command to include a maximum heap size of 1 GB (at least).
${TEPS_JAVA_HOME}/bin/java -Xms512m -Xmx1G
You can run the DLA against a single endpoint using -m option but by default that will fail. There is a technote available that describes how to edit the script so that it will be successful.
http://www-01.ibm.com/support/docview.wss?uid=swg1IV38673
Once you have applied this fix, you can run against a single endpoint, using the format ,<2 letter agent code>. For example
itmcmd execute cq "tmsdla.sh -m itmfve:LZ,lz"
The label attribute in TADDM is a way to explicitly change the display name of an instance. If the label attribute is not populated then TADDM uses an algorithm to generate the display name of each instance based on other populated attributes. It is recommended to only use the label attribute to manually name instances through the TADDM portal. Otherwise, the TMS DLA label name might not be desirable and it is best to let TADDM name instances based on it's own algorithm.
Find all references to cdm:Label in kux_tmsdla.xml, klz_tmsdla.xml, and knt_tmsdla.xml and remove those lines.
The primaryMACAddress attribute in TADDM represents the MAC address of one of the IP interfaces. This attribute is no longer discovered in TADDM by default due to all the duplicate instance issues caused. This attribute should not be discovered. Additionally, if you are using the duplicate reducer discovery extension then populating this attribute via TMS DLA will cause even more problems.
Find all references to cdm:PrimaryMACAddress in kux_tmsdla.xml, klz_tmsdla.xml, and knt_tmsdla.xml and remove those lines.
Depending on your integration scenario, it might make sense to disable discovery of the TMSAgent instances completely. It is important to clarify that there are two main types of data discovered by the TMS DLA; the agents and the instances monitored by the agent. If you only need the instances monitored by the agents then you can safely remove all the TMSAgent instances from the templates. For instance, if your integration scenario is to enrich the TADDM discovered data with ManagedSystemName attributes so that TBSM can consume the data, then you don't need the TMSAgent instances discovered. The BIRT monitoring coverage reports in TADDM also do not require the TMSAgent to be discovered, though the drill-down agent detail will be missing.
Find the tmsdla:cdmsection tag in the template that discovers the TMSAgent instances and remove that entire section. Remove all sections that only create relationships to TMSAgent instances. Also do this for tmsdla_default.xml and tmsdla_final.xml.
Occasionally you will want to disable a template altogether. For example, if you only want to run discovery for data from the OS agents, then you will want to disable the discovery for data from the DB2 agent. Find the template file for the agent you want to disable based on the agent code (e.g. kud for DB2 agents = kud_tmsdla.xml). Change the .xml extension of that template file. Now that template will be skipped during processing because the DLA only loads *_tmsdla.xml template files during processing.
By default, the TMS DLA only discovers non-private IP addresses. The private IP address ranges are excluded in the template files. If you wish for all IP addresses to be discovered then you can remove all of those exclusions.
For OS agents, the Signature attribute is discovered using the "lowest" IP address and corresponding MAC address. Often this attribute is used to reconcile with instances that TADDM discovers so it is important that it be accurate. The following describes a scenario where the Signature attribute is calculated using a private 10.* IP address but those 10.* IP addresses are not discovered and populated in the IdmL book. These instructions assume the Linux OS agent template is being updated but the same concept applies to any template.
Split the query sections that define the DNS name and the lowest IP address.
<tmsdla:temsquery table="KLZ.LNXIPADDR" where="ORIGINNODE='%{MSYSN}' AND IPADDRESS='%{IPADDR}'" at="'%{THRUNODE}'">
<tmsdla:define name="PRI_DNS_NAME" column="DNSNAME"/>
</tmsdla:temsquery>
<tmsdla:temsquery table="KLZ.LNXIPADDR" where="ORIGINNODE='%{MSYSN}' AND IPADDRESS='%{LOWEST_IP_ADDR}'" at="'%{THRUNODE}'">
<tmsdla:define name="MATCHING_INTFNAME" column="INTFNAME"/>
</tmsdla:temsquery>
Remove the LOWEST_IP_ADDR exclusion for the range that you want to use to calculate the Signature. For example, to include 10.* in the calculation REMOVE the following line.
<tmsdla:filter name="LOWEST_IP_ADDR" exclude="10\..+"/>
By default, the TMS DLA discovered SerialNumber attribute for VMware instances is incorrectly formatted. The custom_tmsdla.jar attachment contains transformations to correctly format this value. Download and place that file among the other transformation files and edit the knt_tmsdla.xml and klz_tmsdla.xml file as follows.
<tmsdla:define name="MANUFACTURER" column="COMPVEND"/>
<tmsdla:define name="SERIAL_OVERLOADED" column="COMPID" >
<tmsdla:define name="SERIAL" method="com.ibm.csi.monitoring.tmsdla.VMwareSerialNumber" parm="%{MANUFACTURER}"/>
</tmsdla:define>
Note that the MANUFACTURER definition was moved above the SERIAL definition so that it can be fed in as a parameter.
By default, the TMS DLA discovered Model attribute for Oracle Solaris instances is incorrectly formatted when the value is SUN4V. The value should be lowercase sun4v. The custom_tmsdla.jar attachment contains transformations to correctly format this value. Download and place that file among the other transformation files and edit the kux_tmsdla.xml file as follows.
<tmsdla:define name="MODEL_OVERLOADED" column="MODEL" >
<tmsdla:define name="MODEL" method="com.ibm.csi.monitoring.tmsdla.OracleModel"/>
</tmsdla:define>
By default, the TMS DLA discovered Manufacturer attribute for Oracle Solaris instances is incorrectly formatted. The discovered value is 'Oracle Corporation' and should be 'Oracle'. The custom_tmsdla.jar attachment contains transformations to correctly format this value. Download and place that file among the other transformation files and edit the kux_tmsdla.xml file as follows.
<tmsdla:define name="MANUFACTURER_OVERLOADED" column="VENDOR">
<tmsdla:define name="MANUFACTURER" method="com.ibm.csi.monitoring.tmsdla.OracleManufacturer"/>
</tmsdla:define>
For Solaris global zone instances, the TMS DLA populates the VMID to be 'global'. TADDM discovery leaves this value blank for global zones. Add the following to kux_tmsdla.xml in the tmsdla:filters.Attributes section to exclude this value.
<tmsdla:filter name="PART_ID" exclude="global" />
The value for SystemBoardUUID is incorrect for Oracle Solaris instances. The value actually represents the SystemId attribute. The custom_tmsdla.jar attachment contains transformations to correctly format this value. Download and place that file among the other transformation files and edit the kux_tmsdla.xml file as follows.
<tmsdla:define name="MANUFACTURER_OVERLOADED" column="VENDOR">
<tmsdla:define name="MANUFACTURER" method="com.ibm.csi.monitoring.tmsdla.OracleManufacturer"/>
</tmsdla:define>
<tmsdla:define name="UUID_OVERLOADED" column="UUID" >
<tmsdla:define name="SYS_UUID" method="com.ibm.csi.monitoring.tmsdla.OracleSystemBoardUUID" parm="%{MANUFACTURER}"/>
</tmsdla:define>
Note that the MANUFACTURER definition (enhanced from an earlier best practice) was moved above the UUID definition so that it can be fed in as a parameter.
This is a best practice because it matches the behavior of the sensors and improves data accuracy. Some reports or custom integrations may key off of this attribute to avoid reporting on systems that are not deeply discovered. This attribute was introduced after the TMS DLA was originally developed. For all OperatingSystem instance definitions in the OS agent templates add the following attribute.
<cdm:OSConfidence>100</cdm:OSConfidence>
For all IpV4Address instances, add StringNotation attribute with identical value to dotNotation.
<cdm:net.IpV4Address id="%{IF_NAME}:%{IF_IP_ADDR}:%{IF_MAC_ADDR}-IpV4Address" sourceToken="ip_address=%{IF_IP_ADDR}">
<cdm:DotNotation>%{IF_IP_ADDR}</cdm:DotNotation>
<cdm:StringNotation>%{IF_IP_ADDR}</cdm:StringNotation>
</cdm:net.IpV4Address>
TADDM attribute prioritization rules allow you to configure data source priority at an attribute level. It is recommended that you set the ComputerSystem attribute prioritization so that TADDM discovery is prioritized over the DLA for all the attributes that the DLA discovers except ManagedSystemName. For ManagedSystemName the DLA should be prioritized over TADDM discovery. This is important because there are some version of TADDM where the TPC sensor overwrites the ManagedSystemName and you want to ensure that the TMS DLA is the trusted data source for that attribute.
