HOWTO setup and install New Relic instrumentation
Instructions for Installing the New Relic APM Agent:
1. Log into the appserver as administrator or root/bbuser and go to the %BLACKBOARD_HOME%/apps/tomcat directory
2. Upload newrelic_agent3.7.0.zip to the %BLACKBOARD_HOME%/apps/tomcat directory and unzip it here
3. Once the above steps are complete, a "newrelic" folder will be created at %BLACKBOARD_HOME%/apps/tomcat/newrelic
4. Make sure that this folder and its contents are owned by the bbuser account with full permissions
5. To verify the agent version, you can run "java -jar newrelic.jar -v" (or on Windows, just double-click newrelic.jar). We will not be using the
automated installer option this .jar provides when run with the "install" cmdline argument.
Setting Java Options
1. Make a backup of the wrapper.conf and wrapper.conf.bb files under apps/tomcat/conf & config/tomcat/conf
2. To include the NewRelic Agent into the Blackboard tomcat JVM, edit both wrapper.conf and wrapper.conf.bb under both locations (the
config/tomcat/conf/wrapper.conf.bb file is the PushConfig source for all of these):
a. apps/tomcat/conf
b. config/tomcat/conf
3. Find a free line among the wrapper.java.additional.NNN properties or add a new one below the existing ones (numbers must form a tight
sequence). Typically wrapper.java.additional.29 will be free, so it is suggested to use that.
4. The line should look as follows in wrapper.conf.bb:
wrapper.java.additional.29=-javaagent:@@bbconfig.basedir@@/apps/tomcat/newrelic/newrelic.jar
and in wrapper.conf it would be e.g.:
(UNIX) wrapper.java.additional.29=-javaagent:/usr/local/blackboard/apps/tomcat/newrelic/newrelic.jar
(Windows) wrapper.java.additional.29=-javaagent:C:/blackboard/apps/tomcat/newrelic/newrelic.jar
5. You may also just edit config/tomcat/conf/wrapper.conf.bb and run PushConfigUpdates, but it is easier/safer to first try editing only
apps/tomcat/conf/wrapper.conf and verify that it works with a simple tomcat restart before altering the persistent configuration.
Setting Policy
1. Make a backup of the catalina.policy file in both %BLACKBOARD_HOME%/apps/tomcat/conf
& %BLACKBOARD_HOME%/config/tomcat/conf directories
2. Append the following grant statements to the catalina.policy file in both locations (the one in apps/tomcat/conf is a copy of the one
in config/tomcat/conf, created by PushConfigUpdates):
// All rights to NewRelic agent
grant codeBase "file:${catalina.base}/newrelic/newrelic.jar" {
permission java.security.AllPermission;
};
grant {
permission java.lang.RuntimePermission "accessDeclaredMembers";
permission java.lang.reflect.ReflectPermission
"suppressAccessChecks";
permission java.lang.RuntimePermission "getClassLoader";
permission java.lang.RuntimePermission
"accessClassInPackage.org.apache.catalina.connector";
};
3. Run PushConfigUpdates and wait until startup has completed
4. Check whether %BLACKBOARD_HOME%/apps/tomcat/newrelic/logs/newrelic_agent.log has been created
5. The newrelic_agent.log file should confirm that data is being sent to https://rpm.newrelic.com/XXX/.. or similar.
6. If the connection is reported as unsuccessful, check your firewall configuration (see below).
Changing New Relic License Key
1. Edit newrelic.yml file located at %BLACKBOARD_HOME%/apps/tomcat/newrelic/newrelic.yml
2. Specify the license_key parameter as follows (this is necessary to classify your system among the Blackboard-monitored environments):
2.
license_key: '05290901b025b87a9353ab6325b089f012a0e6b5'
3. Search for app_name and set it to a client-specific name. The Client_Specific_Name value represents the client/institution and must be
the same across all of a client's app servers, so they are identifiable as part of the same environment in the NewRelic reporting service.
4. (If the client has multiple different environments on which they wish to install NewRelic, they can still identify them with the same
app_name, but distinguish them via the "environment" property, as explained at the bottom of this config file.)
5. Save the file
6. Restart the Tomcat service
7. Perform these same steps on the other appservers in a rolling fashion. Optionally only enable the agent on selected appservers in a
larger environment.
Firewall configuration
If your system has an outgoing firewall in place that prevents connections from your appservers to the web except for specific whitelisted
addresses or hosts, make sure the collector.newrelic.com and rpm.newrelic.com hosts are whitelisted. We've also observed requests being made
to secondary servers in the newrelic.com domain, so you may need to open up the entire domain. According to NewRelic's documentation, you
can verify connectivity to their system by making the following request from the appserver with the widely available curl tool (or similar):
curl -v https://collector.newrelic.com/status/mongrel
NOTE:
Please send us the newrelic_agent.log file after the installation is complete - you will find it in blackboard/apps/tomcat/newrelic/logs. This will allow
us to verify correct configuration and easily identify your site in their SaaS reporting environment.
Uninstallation
On each appserver individually, perform the following steps:
1. Remove the -javaagent:... value from the wrapper.java.additional.29 parameter in the wrapper.conf and wrapper.conf.bb files in both
config/tomcat/conf and apps/tomcat/conf (make sure you don't miss any of these, or you may cause tomcat to not start at some point in
the future).
2. Remove the section added above from catalina.policy in both apps/tomcat/conf/ and config/tomcat/conf/ (or simply revert to your backup
copy).
3. Restart the tomcat service.
4. After verifying that the application started correctly, remove the apps/tomcat/newrelic/ folder in its entirety, as it is no longer needed.
Should you ever wish to disable the agent only temporarily, without uninstalling it completely, simply remove the javaagent argument from
wrapper.conf(.bb) again (taking care not to break the sequence of numbered arguments) and restart tomcat.
