In order to run the collector, Java 8 or later must be installed.
- Download the release archive and extract it to the disk. We will refer to the directory where it is extracted as the installation directory
- In the installation directory, copy the file cisco-rtmt-collector.json.sample to cisco-rtmt-collector.json
- Edit cisco-rtmt-collector.json according to the Configuration section
- Save cisco-rtmt-collector.json
- Run the installation script as root ./install.sh
You will need the account number and the license key for New Relic account that the collector will report to.
-
Edit cisco-rtmt-collector.json.
-
Edit the global section.
a. Replace “enter account number” with your New Relic account number.
b. Replace “enter account number” with your New Relic account number.
c. (If reporting to EU New Relic datacenter). Add attribute “useEU” with a value of true.
.
d. (Optional). The collector will collect metrics every minute. To query less often add a “frequency” element and give it an integer value that is the number of minutes between queries and reporting. If not present then the frequency will be set to 1. -
Collect the RTMT urls that you want to query along with the RTMT hosts associated with each URL.
-
You will need to create an “agent” for each RTMT url that you want to query. Each agent is a JSON entry in the “agents” array.
a. Enter a unique name for the agent. This can be used to differentiate which agent collected the RTMT event.
b. Enter the url for RTMT.
c. Enter a comma separated list of host names that you want query from this url in the “hosts” entry.
d. If a username and password are required to access the RTMT counters then:
i. Add a “security” JSON stanza to the agent.
ii. Add “username” and “password” attributes to the JSON object with values that match those necessary.
-
(Optional). If you plan to query for session counters then populate the sessions stanza. The collector will open a session, add the configured counters and query for them each period. To configure them add a “sessions” stanza. The file sessions.json.sample contains the stanza. Note that multiple sessions can be used. Copy the contents to the agent and configure as follows:
a. Replace “unique name for session” with a unique for the set of session counters being collected.
b. Populate “counters” by adding a counter name to the array. Note that these counter names include ‘\’ and the JSON parser sees it as an escape character so if the name includes a \ denote it as \. Note that the counter name should follow the guidelines found here: Add Session Counter.c. Separate each name with a comma except the last one.
d. Repeat if you want to set up additional sessions and counters. -
Repeat if more agents are needed.
-
(Optional). Congfigure Filters as needed. See the next section.
-
Save cisco-rtmt-collector.json.
Three types of filters can be configured. Each filter depends on the scope of the filter.
The three types are:
- Global - applies to all urls and hosts
- Agent - applies to all hosts associated with the agent's URL.
- Host - applies only to the host with that name.
A filter must include an object name. Optionally it can include counter names. Optionally it can include instance names for multiple instance object names.
The filter can either be include or exclude. The default is exclude.
Collect all RTMT counters except the configured counters.
Only collect the confgured RTMT counters.
To add filters to the configuration, add a "filters" array to the configuration json.
Each filter element has the following structure:
"scope" - required and must be one of these case insenstive strings: "global", "agent" or "host"
"type" - optional. value of "include" or "exclude". default is exclude if not present.
"objectName" - required and is the object name on which to filter
"counters" - optional and is a JSON array of counter names on which to filter
"instances" - optional and is JSON array of instance names on which to filter. Ignored if object name is not multiple instance
The service can be started and stopped by running the appropriate command as root
systemctl start cisco-rtmt-collector
systemctl stop cisco-rtmt-collector
You can generate a list of available counters by:
-
Navigate to /opt/newrelic/cisco-rtmt-collector
-
Run the following command as root: java -cp cisco-rtmt-collector.jar com.newrelic.event.cisco.rtmt.QueryCounters -config_file cisco-rtmt-collector.json
-
This should generate a file named RTMT-Counters.txt
To build the distribution tar file run the command:
./gradlew createPackage
Result is built to build/distributions/
To build the jar file used by the collector:
./gradlew allInOneJar
Result is built to build/distributions/
To uninstall the collector:
- Navigate to /opt/newrelic/cisco-rtmt-collector
- Run the following command as root:
./uninstall.sh
The collector produces a log named cisco_rtmt.log and is created in the directory /opt/newrelic/cisco-rtmt-collector/logs
The default logging level is info for the log. To change the level, add "logging_level" to the global properties in cisco-rtmt-collector.json.
Logging levels are: fatal, error, warn, info, debug, all.
New Relic has open-sourced this project. This project is provided AS-IS WITHOUT WARRANTY OR DEDICATED SUPPORT. Issues and contributions should be reported to the project here on GitHub. We encourage you to bring your experiences and questions to the Explorers Hub where our community members collaborate on solutions and new ideas.
We encourage your contributions to improve Cisco RTMT Collector! Keep in mind when you submit your pull request, you'll need to sign the CLA via the click-through using CLA-Assistant. You only have to sign the CLA one time per project. If you have any questions, or to execute our corporate CLA, required if your contribution is on behalf of a company, please drop us an email at opensource@newrelic.com.
A note about vulnerabilities
As noted in our security policy, New Relic is committed to the privacy and security of our customers and their data. We believe that providing coordinated disclosure by security researchers and engaging with the security community are important means to achieve our security goals.
If you believe you have found a security vulnerability in this project or any of New Relic's products or websites, we welcome and greatly appreciate you reporting it to New Relic through HackerOne.
Cisco RTMT Collector is licensed under the Apache 2.0 License.