Technical Blog Post
Abstract
All you ever wanted to know about Topology Builder agents - Issue #2 AliasesCleanupAgent
Body
As mentioned in my earlier post, the first topology builder agent I will discuss is the AliasesCleanup agent. This agent is an important agent because it cleans up old aliases which could cause unexpected merge conditions to occur in TADDM.
You may be asking 'what is an alias?', so without going into too much detail, an 'alias' is simply a representation of a naming rule for a specific guid. TADDM determines if two objects are the same by looking for matching naming rules. For example, manufacturer, model and serial number are attributes for one of the ComputerSystem class naming rules. If you have two computer systems whose manufacturer is IBM, model is 5555 and serial number is 1234567, TADDM will merge those into one, as these attributes should be unique to a single computer system. Each guid can have multiple aliases, one for each possible naming rule if the attributes are discovered. If any naming alias naming rule matches between two CIs of a similar class, they will be merged into one.
If you would like to learn more about aliases and naming rules, check out this link to an education assistant module on the topic;
Anyway, these 'aliases' are stored in a database table called 'aliases' and it is the purpose of the AliasesCleanup agent to keep it as up to date as possible.
The AliasesCleanupAgent was introduced in TADDM 7.2.1 and updated further in 7.2.1 Fixpack 3 to improve performance and correct issues found in the field.
The agent validates only some types of naming rules by comparing the aliases rows with the api returned attributes for the guid. It validates the following;
1. All simple aliases (without “,” in alias name )
2. Four context aliases:
- Hostname, VMID
- Hostname,lparname
- Hostname,MIFID
- WPAR,name
The agent also removes aliases if an ObjectNotFoundException occurs when the agent api queries the guid.
Please note that the agent does not remove any row where the master alias matches the alias guid as this row is required for the guid to be valid. So even if the naming rule is no longer valid for the aliases row where master guid=alias guid, it cannot be deleted. If an unexpected over merge is found with verify-data, and this particular alias in incorrect, it is best to delete the guid via api and then re-discover the object.
This agent also removes orphan rows in aliases and persobj table, eg. rows for which there is no corresponding class table entries for the guid.
Properties for this agent
The following collation.properties entries apply to this topology builder agent;
com.ibm.cdb.topomgr.topobuilder.max.row.fetch
This property configures the batch size used to fetch aliases from aliases table.
Default is: 1000.
If the property is set to -1 , then the agent does not verify the aliases.
com.ibm.cdb.topomgr.topobuilder.max.row.delete
This property configures the batch size used to delete aliases.
The default value is: 100.
If the property is set to -1 , then the agent does not remove aliases, it only reports corrupted aliases in the agent log.
com.ibm.cdb.topomgr.topobuilder.agents.AliasesCleanupAgent.maxNumberOfMastersToScan
This property configures number of CI for which aliases should be verified during a single agent run.
The default value is 1000. The number of CIs that are verified is this value * com.ibm.cdb.topomgr.topobuilder.max.row.fetch, so 1,000,000 by default.
Note that increasing any of the above properties will cause the agent to take longer to run and will require more database transaction (DB2) or undo (Oracle) space.
com.ibm.cdb.topomgr.topobuilder.cleanupOrphanedAliasesAndPersobj
This property enables/disables cleanup of aliases in aliases table and guids in persobj table which do not have any corresponding CI.
The default value is true which means the agent does the cleanup.
com.ibm.cdb.topomgr.topobuilder.DelayToRemoveAliases
This property defines how old (in hours) aliases without a corresponding CI should be before the agent attempts to remove them. This is to protect from removing aliases which were just registered in aliases table but the CI has not completed storing yet.
The default value is 12 hours which means that orphaned aliases older than 12 hours are removed by the agent. Use this property with caution. Do not set to smaller values. The minimum value considered should be greater than the longest discovery performed on the system.
Agent Logging
With INFO logging, you can see useful messages in the log/services/TopologyBuilder.log or /log/agents/AliasesCleanupAgent.log about the work the agent is going to do or has done;
INFO agents.AliasesCleanupAgent - ALIASES SCAN STARTED FROM TOP OF TABLE, cycleId: 1376241544302
INFO agents.AliasesCleanupAgent - ALIASES TABLE SCAN CONTINUED, cycleId: 1376241544302
INFO agents.AliasesCleanupAgent - ALIASES SCAN ENDED, REACHED END OF TABLE, cycleId: 1376241544302
INFO agents.AliasesCleanupAgent - Total number of master aliases scanned = 0, cycleId = 1376241544302
INFO agents.AliasesCleanupAgent - Number of master aliases scanned in current run = 10113000
INFO agents.AliasesCleanupAgent - Number of aliases to analize = 10759
INFO agents.AliasesCleanupAgent - Number of masters to analize = 10725
INFO agents.AliasesCleanupAgent - Total number of master aliases already scanned = 10113000, cycleId = 1376241544302
In the above message you can see that the agent was able to process the entire aliases table in one scan as noted by the "ALIASES SCAN STARTED FROM TOP OF TABLE" and "ALIASES SCAN ENDED, REACHED END OF TABLE". If your aliases table is large, it may take multiple runs of the agent to complete the entire scan.
With DEBUG logging you can see the values of the previously discussed properties;
DEBUG agents.AliasesCleanupAgent - MaxRowNumToFetch = 1000
DEBUG agents.AliasesCleanupAgent - MaxRowNumToDelete = 100
DEBUG agents.AliasesCleanupAgent - MaxNumberOfMastersToScan = 1000000
DEBUG agents.AliasesCleanupAgent - Processing ALIASES table...
Well I hope that explains what this agent is for and it's importance. If you have any questions, please feel free to comment below.
Next Up : ObjectsWithoutAliasesCleanup - or comment below if you have interest in a particular agent.
UID
ibm11275412