{"id":23478411,"url":"https://github.com/opennms/oce-tools","last_synced_at":"2025-07-28T08:43:10.270Z","repository":{"id":33961944,"uuid":"156645802","full_name":"OpenNMS/oce-tools","owner":"OpenNMS","description":"Utilities for developing and testing OCE","archived":false,"fork":false,"pushed_at":"2022-11-16T01:42:10.000Z","size":436,"stargazers_count":1,"open_issues_count":4,"forks_count":0,"subscribers_count":14,"default_branch":"master","last_synced_at":"2025-04-13T18:54:09.388Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/OpenNMS.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-11-08T03:36:41.000Z","updated_at":"2020-10-13T19:16:10.000Z","dependencies_parsed_at":"2022-08-25T09:10:27.440Z","dependency_job_id":null,"html_url":"https://github.com/OpenNMS/oce-tools","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/OpenNMS/oce-tools","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenNMS%2Foce-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenNMS%2Foce-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenNMS%2Foce-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenNMS%2Foce-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/OpenNMS","download_url":"https://codeload.github.com/OpenNMS/oce-tools/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/OpenNMS%2Foce-tools/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":265205775,"owners_count":23727511,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-24T19:19:24.164Z","updated_at":"2025-07-13T21:08:26.942Z","avatar_url":"https://github.com/OpenNMS.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# OpenNMS Correlation Engine (OCE) Tools [![CircleCI](https://circleci.com/gh/OpenNMS/oce-tools.svg?style=svg)](https://circleci.com/gh/OpenNMS/oce-tools)\n\nThis repository contains a collection of tools and utilities to help develop, test, and validate the functionality of the OCE.\n\n# Building\n\n## Requirements\n\nBefore building ensure you have built and installed (`mvn install`) the artifacts from:\n* The `master` branch of [OCE](https://github.com/OpenNMS/oce)\n* The `features/sextant` branch of [OpenNMS](https://github.com/OpenNMS/opennms/tree/features/sextant)\n* The `features/events/syslog` project in [OpenNMS](https://github.com/OpenNMS/opennms)\n\n## Compiling\n\nCompile the project with:\n\n```\nmvn clean package\n```\n\n# Usage\n\nMost of the commands interact with data stored in Elasticsearch.\n\n```sh\nmkdir -p ~/.oce\necho 'clusters:\n  localhost:\n    url: http://localhost:9200\n    read-timeout: 120000\n    conn-timeout: 30000\n    opennms-event-index: opennms-events-raw-*\n    opennms-alarm-index: opennms-alarms-*' \u003e ~/.oce/es-config.yaml\n```\n\nYou can run the tool and enumerate the available commands using:\n```\njava -jar main/target/oce-tools.jar --help\n```\n\nIn the remainder of the document, we'll alias this as `oce-tools` i.e.:\n```\nalias oce-tools=\"java -jar ~/git/oce-tools/main/target/oce-tools.jar\"\n```\n\n## Commands\n\n### cpn-report\n\nThis command can be used to find and automatically download .csv reports from CPN.\nIt assumes that the `Detailed Traps`, `Detailed Service Events`, `Detailed Syslogs` and `Detailed Tickets` reports are scheduled to be executed on a daily basis at the same times.\n\nExample usage:\n```\noce-tools cpn-report --url https://ana-cluster:6081/ana --username onms --password onms --output /tmp/cpn-exports/ --from \"Nov 4 2018\"\n```\n\n#### BQL\n\nThis command can also be leverage to run arbitrary BQL command (synchronously) against CPN i.e.\n```\necho '\u003c?xml version=\"1.0\" encoding=\"UTF-8\"?\u003e\n\u003ccommand name=\"DeviceList\"\u003e\u003c/command\u003e' \u003e /tmp/cpn.get.device.list.xml\noce-tools cpn-report --url https://ana-cluster:6081/ana --username onms --password onms --execute /tmp/cpn.get.device.list.xml\n```\n\n### cpn-csv-import\n\nThis command imports a series of .csv files exported by CPN into Elasticsearch.\n\nAll of the documents have unique IDs, so you re-import the same data many times without worrying about duplicates.\n\nExample usage:\n```\noce-tools cpn-csv-import --source=\"/tmp/cpn-exports/\" --timezone=\"America/Chicago\"\n```\n\n### cpn-oce-export\n\nThis command will generate .xml file suitable for importing with the JAXB datasource in OCE.\n\nThese files can be then be used for simulations and comparative analysis.\n\nExample usage:\n```\noce-tools cpn-oce-export --from \"Nov 4 2018\" --to \"Nov 5 2018\" --output /tmp\n```\n\n#### Using the data for simulations\n\nOnce the data has been exported, you can adapt the following commands to:\n1. Simulate the situation generation from the same list of alarms\n1. Compare the generated situations to the tickets and calculate a score\n\n```\nfeature:install oce-features-shell oce-engine-cluster\noce:process-alarms -i /tmp/cpn.alarms.xml -o /tmp/oce.situations.xml -e cluster\noce:score-situations -s peer /tmp/cpn.situations.xml /tmp/oce.situations.xml\n```\n\n### cpn-opennms-event-definition-audit\n\nValidates whether or not this tool has knowledge of the event definitions for all of the CPN events that have occurred in the given time range.\n\nThis can be used to validate whether or not the tool knows how to generate similar events for all of the events that have actually occurred.\n\nExample usage:\n```\noce-tools cpn-opennms-event-definition-audit --from \"Nov 4 2018\" --to \"Nov 5 2018\"\n```\n\n### cpn-opennms-event-handling-audit\n\nGenerate SNMP traps and syslog messages for all of the known types and verifies that the corresponding alarms are created in OpenNMS.\n\nWhen used in conjunction with the `cpn-opennms-event-definition-audit` this helps ensure that the system is capable of handling all of the known event types.\n\nExample usage:\n```\noce-tools cpn-opennms-event-handling-audit \\\n  --node-a-label localhost --node-a-id 1 --node-a-ifindex 2 --node-a-ifdescr ens33 \\\n  --node-z-label localhost --node-z-id 1 --node-z-ifindex 1 --node-z-ifdescr lo \\\n  --opennms-host localhost\n```\n\n### cpn-opennms-event-materialization-audit\n\nMatch CPN events (syslogs \u0026 traps) to OpenNMS events for the given time range.\nThis can be used to help ensure that both systems are receiving the same events.\n\nThis requires OpenNMS events and CPN events to be available in the same Elastisearch instance.\n\nExample usage:\n```\noce-tools cpn-opennms-event-materialization-audit --from \"Nov 4 2018\" --to \"Nov 5 2018\"\n```\n\n### cpn-opennms-situation-materialization-audit\n\nMatch CPN tickets (particularly the syslogs \u0026 traps alarms they contain) to OpenNMS situations for the given time range.\nThis can be used to help validate whether or not both systems are generating similar situations/tickets.\n\nThis requires OpenNMS events, OpenNMS alarms, CPN events and CPN tickets to be available in the same Elastisearch instance.\n\nExample usage:\n```\noce-tools cpn-opennms-situation-materialization-audit --from \"Oct 25th 2018\" --to \"Oct 26th 2018\"\n```\n\n### generate-kem-config\n\nGenerate the configuration for the KEM tool based on the known traps and syslog messages.\n\nExample usage:\n```\noce-tools generate-kem-config\n```\n\n### cpn-opennms-syslog-audit\n\nReports syslog messages that were not parsed correctly.\n\nExample usage:\n```\noce-tools cpn-opennms-syslog-audit --from \"Oct 1 2018\" --to \"Nov 1 2018\"\n```\n\n\n### tsaudit\n\nTicket-situation audit\n\nExample usage:\n```\noce-tools tsaudit --from \"Jan 6 2019 18:00\" --to \"Jan 7 2019\"\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopennms%2Foce-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopennms%2Foce-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopennms%2Foce-tools/lists"}