• Log inStart now

Install New Relic Java agent with Ansible

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:

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:

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
- include_role:
name: newrelic.newrelic_java_agent

The 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: tomcat, jetty, and wildfly (standalone mode only).


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 setenv.sh file. If the file doesn't exist, it may be created, depending on the server_type.



Required. User and group under which the web server runs. Used to set the ownership of the newrelic.jar and newrelic.yml files.


Optional. Default: true. If set to false, the role does not restart the web server after installing the agent. Note that the agent is not activated until the web server is restarted.


Required (unless restart_web_server is set to false). Service name under which the web server runs. Used by Ansible to restart the web server after the agent is installed.


Optional; default: currentSpecifies the version of the Java agent to install. current will install the latest version. You can also install a specific version, like 5.9.0. For available versions, see Java agent downloads directory.

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, Server:One;Data Center:Primary.

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:

- /path/to/my_instrumentation.xml

See the README and examples on GitHub for more information.

For more help

If you need additional help, file an issue at newrelic/newrelic-java-agent-ansible-role on GitHub.

Copyright © 2023 New Relic Inc.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.