Create alarms with lookup

🟡 Intermediate

snmp alarm

This example shows how to generate alarms from SNMP traps by mapping trap fields to alarm properties using CSV lookup files.

Write Lua parsing rules that use lookup calls to resolve trap OID fields to alarm property values.
Register both the rule files and the CSV lookup files as module resources in the SNMP trap configuration.
Test the lookup resolution by sending a trap and reading the mapped alarm fields in the module logs.

git checkout origin/osp-snmp-trap-configuration .
git checkout origin/osp-alarms-configuration .
git checkout origin/example-snmp-trap-lookups .

Steps

1. Create the parsing rules

All traps will be analyzed in one Lua file : main.rules. From this file you can then do the trap-to-alarm conversion according to your needs.

Note

It is not mandatory but highly recommended to divide the Lua logic into several files. This is what we will do in this example.

Create the root/rules/main.rules file.

/root/rules/main.rules

function main (trap, alarm)
    log("WARN", "A new TRAP is received")
    print_trap_info(trap)
    fill_alarm_from_trap(trap, alarm)
    print_alarm_info(alarm)
end

Create one function in another file (root/rules/functions/create-alarm.rules) to fill the alarms.

/root/rules/functions/create-alarm.rules

function fill_alarm_from_trap(trap, alarm)
    -- Simple lookup return nil if not found
    alarm.summary = lookup("example", "summary")

    -- Lookup with default value return with both case append.
    alarm.severity = lookup("example", "severity", {"root.alarms.severities.exist"}) .. "-" .. lookup("file-1", "severity-not-exit", {"root.alarms.severities.not-exist"})

    -- Lookup with index of csv.
    alarm.source = lookup("example", "source", 1)

    -- Lookup with index of csv and default value.
    alarm.serial = lookup("example", "serial", 1, "default") .. "-" .. lookup("file-1", "serial-not-exist", 1, "default")
end

2. Link the rules and lookups to the SNMP trap module

SNMP trap rules as well as any lookup file they might use need to be registered as module resources in modules/snmp-trap/snmp-trap-1/module.resources

{
    "resources": [
        {
            "source": "root/rules/",
            "destination": "rules/"
        },
        {
            "source": "default-functions/snmp-trap/",
            "destination": "rules/default-fonctions/"
        },
        {
            "source": "lookups/",
            "destination": "lookups/"
        }
    ]
}

3. Test from any linux device

Note

By default SNMP-TRAP uses port 162, but it is possible that this port is already used by another service. In this case, you can change the port published in the module.service configuration.

Warning

It is necessary to ensure that port 162 is open. By default, the port is not exposed on the OnSphere stack.

4. Show logs from a console

docker service logs --raw -f osp-stack-1_modules_snmp-trap_snmp-trap-1

5. Send one test TRAP (here using net-snmp from a linux host, but any other trap sender tool could have been used)

snmptrap -v 2c -c public[STACK-IP] ''1.3.6.1.4.1.8072.2.3.0.1 1.3.6.1.4.1.8072.2.3.2.1 i 123456

6. Logs must show something like

osp-stack-1_modules_snmp-trap_snmp-trap-1.1.uaacm3r0knp0@manticore    | [2022-05-30 15:27:26.822] [warning] A new TRAP is received
osp-stack-1_modules_snmp-trap_snmp-trap-1.1.uaacm3r0knp0@manticore    | [2022-05-30 15:27:26.822] [info]      New trap
osp-stack-1_modules_snmp-trap_snmp-trap-1.1.uaacm3r0knp0@manticore    | [2022-05-30 15:27:26.822] [info] SnmpMsg oid                : 1.3.6.1.4.1.8072.2.3.0.1
osp-stack-1_modules_snmp-trap_snmp-trap-1.1.uaacm3r0knp0@manticore    | [2022-05-30 15:27:26.822] [info] SnmpMsg type               : TRAP
osp-stack-1_modules_snmp-trap_snmp-trap-1.1.uaacm3r0knp0@manticore    | [2022-05-30 15:27:26.822] [info] SnmpMsg occurrence         : 1653924446822307821
osp-stack-1_modules_snmp-trap_snmp-trap-1.1.uaacm3r0knp0@manticore    | [2022-05-30 15:27:26.822] [info] Community name             : public
osp-stack-1_modules_snmp-trap_snmp-trap-1.1.uaacm3r0knp0@manticore    | [2022-05-30 15:27:26.822] [info] Snmp version               : 1
osp-stack-1_modules_snmp-trap_snmp-trap-1.1.uaacm3r0knp0@manticore    | [2022-05-30 15:27:26.822] [info] Source                     : 172.18.0.1:41946
osp-stack-1_modules_snmp-trap_snmp-trap-1.1.uaacm3r0knp0@manticore    | [2022-05-30 15:27:26.822] [info] Destination                : 0.0.0.0:10162
osp-stack-1_modules_snmp-trap_snmp-trap-1.1.uaacm3r0knp0@manticore    | [2022-05-30 15:27:26.822] [info] Specific-trap              : 1
osp-stack-1_modules_snmp-trap_snmp-trap-1.1.uaacm3r0knp0@manticore    | [2022-05-30 15:27:26.822] [info] SnmpMsg variables bindings :
osp-stack-1_modules_snmp-trap_snmp-trap-1.1.uaacm3r0knp0@manticore    | [2022-05-30 15:27:26.822] [info]  - 1.3.6.1.4.1.8072.2.3.2.1 : 200.0
osp-stack-1_modules_snmp-trap_snmp-trap-1.1.uaacm3r0knp0@manticore    | [2022-05-30 15:27:26.822] [info] -----------------------------------------------------
osp-stack-1_modules_snmp-trap_snmp-trap-1.1.uaacm3r0knp0@manticore    | [2022-05-30 15:27:26.822] [info] Registering [1] user lookups inside...
osp-stack-1_modules_snmp-trap_snmp-trap-1.1.uaacm3r0knp0@manticore    | [2022-05-30 15:27:26.822] [warning] Requested to get element [1] of [serial] from [example] but index is out of range.
osp-stack-1_modules_snmp-trap_snmp-trap-1.1.uaacm3r0knp0@manticore    | [2022-05-30 15:27:26.822] [warning] Requested to get element [1] of [serial-not-exist] from [file-1] but index is out of range.
osp-stack-1_modules_snmp-trap_snmp-trap-1.1.uaacm3r0knp0@manticore    | [2022-05-30 15:27:26.822] [info]      Alarm
osp-stack-1_modules_snmp-trap_snmp-trap-1.1.uaacm3r0knp0@manticore    | [2022-05-30 15:27:26.822] [info] UID             : c7b42233-cfc0-4d47-af4e-51467c9491b6
osp-stack-1_modules_snmp-trap_snmp-trap-1.1.uaacm3r0knp0@manticore    | [2022-05-30 15:27:26.822] [info] Occurrence      : 1653924446822307821
osp-stack-1_modules_snmp-trap_snmp-trap-1.1.uaacm3r0knp0@manticore    | [2022-05-30 15:27:26.822] [info] Summary         : my-summary-1
osp-stack-1_modules_snmp-trap_snmp-trap-1.1.uaacm3r0knp0@manticore    | [2022-05-30 15:27:26.822] [info] Location        :
osp-stack-1_modules_snmp-trap_snmp-trap-1.1.uaacm3r0knp0@manticore    | [2022-05-30 15:27:26.822] [info] Severity        : my-severity-1-root.alarms.severities.not-exist
osp-stack-1_modules_snmp-trap_snmp-trap-1.1.uaacm3r0knp0@manticore    | [2022-05-30 15:27:26.822] [info] Source          : my-source-2
osp-stack-1_modules_snmp-trap_snmp-trap-1.1.uaacm3r0knp0@manticore    | [2022-05-30 15:27:26.822] [info] Serial          : default-default
osp-stack-1_modules_snmp-trap_snmp-trap-1.1.uaacm3r0knp0@manticore    | [2022-05-30 15:27:26.822] [info] Tags            :
osp-stack-1_modules_snmp-trap_snmp-trap-1.1.uaacm3r0knp0@manticore    | [2022-05-30 15:27:26.822] [info] Additional info :
osp-stack-1_modules_snmp-trap_snmp-trap-1.1.uaacm3r0knp0@manticore    | [2022-05-30 15:27:26.822] [info] -----------------------------------------------------