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:

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

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.

Variable	Description
`server_type`	Required. Web server used by your application. Possible values are: `tomcat`, `jetty`, and `wildfly` (standalone mode only).
`server_root`	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.
`jvm_conf_file`	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.`
`server_user` `server_group`	Required. User and group under which the web server runs. Used to set the ownership of the `newrelic.jar` and `newrelic.yml` files.
`restart_web_server`	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.
`service_name`	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.
`nr_java_agent_version`	Optional; default: `current`Specifies 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.

Variable	Description
`license_key`	Required. Your New Relic license key.
`app_name`	Required. Name of the application being instrumented. For more details, see App naming.
`proxy_host` `proxy_port` `proxy_user` `proxy_password` `proxy_scheme`	Optional. If you connect to the New Relic collector via a proxy, you can configure your proxy settings with these values.
`labels`	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:

vars:
  custom_instrumentation_files:
    - /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.