A new device integration: from MIBs to probe rules
Prompts that let IBM Bob integrate a new device into Netcool from what an integration team receives, a trap list and the vendors' MIBs: a catalogue of every trap, the probe rules and lookups in the operator's folder tree, and a review that sends a test trap of every kind through the rules.
The use case
A new network platform comes into service: a cluster of appliances with their management servers, switches and servers. Its alarms must reach Netcool. The integration team receives a business requirement, a spreadsheet of the traps in scope (one sheet per component, with severities and the event text the vendor recommends), and a zip of vendor MIBs. From those, an engineer writes the rules of the SNMP trap probe: one case per trap, the fields of each event, and which trap clears which. This is the largest part of an integration, and it is done by hand.
The request: Bob should generate those rules from the MIBs and the trap list, following the operator's own coding standard for rules files (the same standard as in the first use case: a fixed folder tree, every path through $NC_RULES_HOME, data in lookups rather than in conditions, one log format, no commented-out code).
Why not let Bob write the rules freely
A trap list and a set of MIBs disagree in many small ways, and a rules file written by hand carries those disagreements into production, where they show as alarms that never clear, or clear the wrong problem, or say nothing useful. On the operator's real inputs the skill found, among others:
- OIDs with a typo, and rows whose name points to one MIB trap while their OID and description point to another;
- traps named differently from the MIB, and traps no supplied MIB defines;
- the same trap listed in two sheets with two different severities;
- alarms that do not arrive as traps of their own, but inside one trap of the management server, with the alarm's number hidden in the index of its variables;
- event texts that name a variable the trap does not have, or the wrong one of its variables;
- servers that signal a recovery with the same trap and a value of one variable, rather than with a clearing trap.
None of these is visible in a rules file that loads without errors. So the rules are written by the skill, and Bob decides only what needs reading and judgement.
How it works
A second skill for Bob, trap-rules, generic like the first: any trap list (a spreadsheet or a CSV with a name and an OID column), any SMIv1 or SMIv2 MIBs, and the folder tree of the standards document in the workspace. It has three tasks, each a command that ends with a gate.
1 · Catalogue
The skill reads every sheet and every MIB, matches each row to a MIB trap by OID and by name, and writes one block per open decision, each with its facts and a proposal. Bob decides; the skill writes the catalogue.
2 · Generate
From the catalogue, the skill proposes every trap's AlertKey and Summary and flags the texts that disagree with the MIB. Bob decides; the skill writes the rules folder and its lookups, then checks them.
3 · Review
A check of the rules against the catalogue that does not trust how they were made, and a small rules interpreter that sends one test trap of every kind through them and replays every problem with its clear.
What Bob decides
| Decision | What the skill gives Bob |
|---|---|
| A row that disagrees with the MIB | The row, the MIB trap at its OID, the MIB trap with its name, and which description matches |
| A trap no MIB defines | Keep it from the sheet, or drop it; the report asks the owner for the MIB |
| Severities | Each severity word of the sheet, with a proposed number and type; each trap listed with two severities |
| Alarms inside another trap | The MIB trap whose variables are indexed by an alarm number, and the trap that clears them |
| Which trap clears which | Groups found by name, problems with no clear, and the variable values the MIB defines as a recovery |
| Key and summary | A proposal for every trap, from the sheet's text or the MIB; the texts that name a variable the trap does not have |
What the skill writes
rules/<name>/
├── <name>.master.rules entry point: dispatch by trap, then the fields
├── config/<name>.master.include.rules every table declaration
├── config/<name>.common.constants.rules values every event starts from
├── transformation_rules/<vendor>.rules one case per trap: variables named, @AlertKey, @Summary
├── transformation_rules/field_normalization.rules severity, type, group, expiry from the lookup; @Identifier
└── lookups/
├── probe_specific/<name>_traps.lookup event id -> name, agent, group, severity, type, expiry, flags
├── probe_specific/<name>_alarm_ids.lookup alarm number -> event id, alarm name
└── constants/field_normalization.constant.rules value maps of enumerated variables
Every value that is data lives in a lookup, as the standard asks. The alarms that arrive inside the management server's trap are fully data-driven: the rules take the alarm's number from the index of its variables, and one lookup gives everything else.
The prompts
Three prompts, in the same three-part form as the other use cases: the verb and what, Write and the report, Do not and the limit. A fix and a second review follow only when the review finds something; a fix changes a decision and generates again, never the rules by hand.
Catalogue the traps of inputs/<trap list>.xlsx against the MIBs in inputs/mibs. Write reports/trap-catalogue.md. Do not write any rules.
Generate the rules for reports/trap-catalogue.md under rules/, following inputs/<standards>.txt. Write reports/rules-generated.md. Do not decide what is the client's to decide.
Review rules/ against reports/trap-catalogue.md. Write reports/rules-review.md. Do not fix anything.
Questions people ask
What if the trap list and the MIBs do not agree?
The catalogue is built in two passes:
- The skill reads every sheet and every MIB and matches each row of the list to a MIB trap, by OID and by name. Every disagreement it finds becomes a decision block in the notes file, with the facts and a proposal. It finds the same things every time.
- Bob decides each block. The gate does not pass while a block is undecided or a trap has no severity.
What happens in each case:
| Case | What happens |
|---|---|
| A trap is in the list but in no MIB that was sent | It is kept, with the OID and the severity from the list. Its variables cannot be named, and the report asks the operator for the MIB |
| An OID one digit away from a MIB OID | The MIB's OID is proposed, and the report lists the correction |
| A row whose name and OID point to two different traps | The trap is chosen by its description, and the report asks the operator to confirm |
| A trap listed twice with two severities | One severity is proposed, and the report asks the operator to confirm |
| A problem with no matching clear | It stays a problem that is cleared by hand, and the report asks whether it should expire instead |
| A trap a MIB defines but the list does not ask for | It is not catalogued: the list sets the scope |
The limits. The catalogue checks the list against the MIBs, not against the device. If the device sends a trap that neither the list nor a MIB names, the rules still give it an event, with an event id that marks it as unknown, so it is seen rather than lost. If the list and the MIB are both wrong in the same way, nothing here can tell.
What if the skill cannot propose a value?
The generation also works in two passes:
- The skill proposes, from the catalogue, the file layout, the expiry of events, and each trap's group, key and summary. It flags what it cannot settle: an event text in the trap list that names a variable the trap does not carry, or a trap with no text to build a summary from. Those blocks are left open, with the facts.
- Bob writes the open blocks and accepts or changes the proposals. No rule is written until every block is decided, and the gate refuses a summary that names a variable the trap does not have.
Choices that belong to the operator are not made by Bob: the domain folder the rules go into, the event field that carries the service-impact flag, and which severity wins when two sources disagree. They are proposed and listed as questions in the report.
The limits. The rules are generated as text and checked by the review and its simulator (prompt 3). They have not been loaded by a real probe.
What does the simulator check, and what can it miss?
The review works in two passes:
- A check of the rules as text: syntax, every path through
$NC_RULES_HOME, the log format, no commented-out code, one case per catalogue trap, event ids, severities and types, and the key of each problem and its clear. - The simulator, a small interpreter of the rules language. It sends one test trap through the rules for every trap in the catalogue and one for every alarm number, then each problem followed by its clear, and one trap that is in no list. It compares each event with the catalogue. A clear must have the same Node, AlertGroup and AlertKey as its problem, so that it closes its own problem and no other.
Each finding has its file and line, and Bob decides it: a fix, a question for the operator, or not a defect, with the reason the files show.
The limits. The simulator is not the probe. It runs the parts of the rules language these rules use, with test values built from the catalogue, not real traps from the devices. Before production the rules still need the probe's own syntax check, a load in a test probe and a real test trap of each kind. The review's last section, Not checked, says so.
What was checked, and the run in Bob
| Step | Result |
|---|---|
| The inputs | The operator's trap list (seven sheets: the service-impacting alarms, all application traps, the management server's alarm format, server resource thresholds, switch, and two server hardware vendors) and 63 MIB files: 2,116 trap definitions read, every one placed. The catalogue holds 174 traps and 165 alarm numbers. |
| Before Bob: a stand-in | An AI agent standing in for Bob, reading only the workspace rule and the skill, ran the three prompts and reported what was unclear. Its most serious point: two different clear groups could be given the same AlertGroup, so a clear of one would close the other's problem. The gate and the simulator now refuse it; nine smaller points were fixed the same way. |
| The review | Eleven defects planted in a copy of the rules (a changed severity, a missing case, an absolute path, a problem and clear with different keys, a variable the trap does not have, commented-out code, a log line without the node, an unset variable, a wrong clear value, an open brace, a missing alarm number) were all found. |
| First prompt in Bob | The gate passed in a minute, but Bob had accepted every proposal, so the judgement calls were missing: threshold objects left without a trap, a power-off with no clear, a cold start that would never clear. The lesson: a gate is only as good as the proposals Bob accepts. The skill now proposes those judgements itself, and leaves a block open only where Bob must write something. |
| Clean run | All three gates passed at the first attempt, in one new chat with nothing typed but the three prompts: about three and a half minutes and 2.18 Bob coins. The catalogue was identical to the one the proposals give; Bob wrote the two summaries it had to write; 13 rules files with 174 cases; the review found nothing, with 172 test traps, 165 test alarms and 54 problem/clear pairs replayed in the simulator. |
| The skill | 48 automated tests on small synthetic MIBs and trap lists. |
Questions the run leaves for the operator
Each report ends with the questions only the operator can answer, for example: which domain folder the rules belong in; whether alarms forwarded by the management server keep the server as their node; whose severity wins when the trap list and the alarm disagree; the MIBs not supplied; the traps listed with two severities; and the problems that have no clear and would stay open.
Still to come: loading the rules in a test probe and sending a test trap of each kind, which needs the operator's environment.
Running it
- Open the integration's workspace folder in IBM Bob. It holds the trap list, the MIBs and the standards document under
inputs/, and the skill under.bob/. - Start a new chat in the built-in Agent mode and send the prompts in order.
- After each prompt, Bob's command should end with
Gate: passed. Read the report it names, and its questions for the owner, before sending the next one. - Before production: load the rules in a test probe, check the syntax with
nco_p_syntax, and send a test trap of each kind.