APM for Java allows you to use an Ansible role for installation and configuration.
Compatibility and requirements
New Relic's Ansible role for the Java agent is open source and community-supported. It supports setting up our Java agent to instrument applications running under Tomcat, Jetty, and Wildfly (formerly JBoss) on Linux servers. The most common agent parameters can be configured through Ansible variables.
You'll need to install Ansible to run this role. Ansible is run from a central server to configure target hosts; these hosts must be running Linux and have
unzip installed. The role should be compatible with most popular Linux distributions.
Overview of process
There are several steps that may be involved for installation and configuration:
- Install the role
- Incorporate role in your playbook
- Configure the role
- Configure the agent
- Enable custom instrumentation (optional)
Step 1. Install the role
To install this role, use the
ansible-galaxy command on the system where you run Ansible:
$ ansible-galaxy install newrelic.newrelic_java_agent
This will download the role from Ansible Galaxy and make it available for use in Ansible playbooks.
Step 2. Incorporate the role into playbook
You'll need to call the role from your playbook using the
include_role module. The role's GitHub repository contains an example playbook for you to start from, which looks like this:
- hosts: YOUR_HOST_GROUP vars: nr_java_agent_config: license_key: YOUR_LICENSE_KEY app_name: YOUR_APP_NAME log_file_path: /tmp/newrelic server_type: tomcat server_root: /var/lib/tomcat8 jvm_conf_file: /usr/share/tomcat8/bin/setenv.sh server_user: tomcat8 server_group: tomcat8 service_name: tomcat8 restart_web_server: true tasks: - include_role: name: newrelic.newrelic_java_agent
vars section contains a dictionary called
nr_java_agent_config, which holds settings for the agent itself, and a number of variables for configuring the role's installation process. See the sections on agent configuration and role configuration for details.
Step 3. Configure the role
These variables are used to configure the install process. Most are required. For more information, see the examples on GitHub.
||Required. Web server used by your application. Possible values are:
||Required. Location of the web server on the host. The agent's JAR, configuration, and (by default) log files will live in a subdirectory of this directory.|
||Required. Path to the web server configuration file to reference the New Relic Java agent. For Tomcat, for instance, it's typically the
||Required. User and group under which the web server runs. Used to set the ownership of the
Step 4. Configure the agent
The following variables are used to configure the Java agent itself. These are just a few of the available options. For a full list of supported variables, see the README file on GitHub. For more about how to configure the agent, see Java agent configuration.
||Required. Your New Relic license key.|
||Required. Name of the application being instrumented. For more details, see App naming.|
||Optional. If you connect to the New Relic collector via a proxy, you can configure your proxy settings with these values.|
||Optional. User-configurable custom labels for the agent. Labels are name-value pairs. Names and values are limited to 255 characters and cannot contain colons (:) nor semicolons (;). Value should be a semicolon-separated list of key-value pairs, for example
Step 5. Enable custom instrumentation (optional)
If you want to enable custom instrumentation, you can provide a list of XML files using the
custom_instrumentation_files variable. For instance, you can specify that all Java agents being installed should use a file called
my_instrumentation.xml by adding something like the following to your playbook:
vars: custom_instrumentation_files: - /path/to/my_instrumentation.xml
For more help
If you need additional help, file an issue at newrelic/newrelic-java-agent-ansible-role on GitHub.