Shell Commands

The Kafka Producer also provides a series of shell commands to help administer and debug the service.

opennms:kafka-list-alarms

Use the list-alarms command to enumerate the reduction keys and show the associated event labels for the alarms that are present in the topic. This command leverages functionality used by the alarm synchronization process, and as a result this must be enabled for this command to function.

$ ssh -p 8101 admin@localhost
...
admin@opennms> opennms:kafka-list-alarms
uei.opennms.org/alarms/trigger:n33:0.0.0.0:HTTPS_POOLs
        Alarm: Generic Trigger

kafka-producer:sync-alarms

Use the sync-alarms command to manually trigger the alarm synchronization process.

$ ssh -p 8101 admin@localhost
...
admin@opennms> opennms:kafka-sync-alarms
Performing synchronization of alarms from the database with those in the ktable.
Executed 1 updates in 47ms.

Number of reduction keys in ktable: 4
Number of reduction keys in the db: 4 (4 alarms total)
Reduction keys added to the ktable: (None)
Reduction keys deleted from the ktable: (None)
Reduction keys updated in the ktable:
        uei.opennms.org/nodes/nodeLostService::1:127.0.0.1:Minion-RPC

opennms:kafka-evaluate-filter

Use the evaluate-filter command to test arbitrary SpEL filtering expressions against alarms or events.

Evaluating Filters against Alarms

To test a filter against an alarm, specify the alarm’s database ID and the expression to test:

admin@opennms> opennms:kafka-evaluate-filter --alarm-id 57 "getReductionKey().contains('n33')"
SPEL Expression: getReductionKey().contains('n33')
Alarm with ID 57 has reduction key: uei.opennms.org/alarms/trigger:n33:0.0.0.0:HTTPSPOOLs
Result: true

Evaluating Filters against Events

To test a filter against an event, specify the event’s UEI and the expression to test:

admin@opennms> opennms:kafka-evaluate-filter --event-uei uei.opennms.org/alarms/trigger "getUei().contains('alarm')"
SPEL Expression: getUei().contains('alarm')
Event has UEI: uei.opennms.org/alarms/trigger
Result: true

In this case, a new event will be created with the given UEI, and the filter will be evaluated against this new event object. At this time, existing events cannot be referenced by this tool, so this functionality only serves to help make sure the expressions are syntactically valid.

opennms:kafka-metric-routing-test

Use the kafka-metric-routing-test command to see which topic collected metrics for a node, interface, or service would be routed to, and which meta-data definition decided it. See Route metrics to multiple topics.

The command reads the live configuration, so it also works while metricRouting.enabled is still false — useful for checking meta-data before switching routing on.

admin@opennms> opennms:kafka-metric-routing-test -n 1 -i 10.0.0.1 -s SNMP
Metric routing: enabled
Meta-data key : requisition:metricRouting.package
Default topic : metrics
---
Node          : 1
Interface     : 10.0.0.1
Service       : SNMP
---
Meta-data value: 'foobar'
Resolved from  : SERVICE
Outcome        : ROUTED - the meta-data value is used as the topic name
Topic          : foobar
---
Counters:
  metricRouting.routed.foobar                        1420
  metricRouting.unmapped                            98311

Specify the node with -n (a node ID or foreignSource:foreignId).

Add -i for the interface the collecting service is assigned to and -s for that service; the two together are what exercise the service scope. Omit them to see what a collection would resolve to from the node’s meta-data alone.

Resolved topics are cached, so a meta-data change made through a requisition import or the REST API can take a few minutes to show up. Pass -c (--clear-cache) to drop the cached decisions first.