Ansible role: New Relic Java agent

This role installs and configures the New Relic Java agent. It should work with minimal configuration for applications running under Tomcat, Jetty, or Wildfly. We aim to support the most popular Java web servers over time.

• Requirements
• Installation
• Configuration
  • Role configuration variables
  • Agent configuration variables
  • Other agent-specific configuration
  • Using your own agent config file
• Example usage
• Community
• Issues / Enhancement Requests
• License

Requirements

The unzip command must be available on the target hosts.

Installation

The recommended way to install the role is to use Ansible Galaxy:

$ ansible-galaxy install newrelic.new_relic_java_agent

If you want to contribute to the role, you can clone this repo and make changes to it, then install it locally by running:

sh examples/install_role.sh

Depending on how Ansible is installed on your system, you may need to preface the above command with sudo.

Configuration

This role uses variables for two purposes: role configuration and agent configuration.

Role configuration variables describe how your hosts are set up so that the role can install the agent files to the right location and set up your Java environment to run the agent.

Agent configuration variables can be set up globally in your playbook or per host or group in your inventory file. They are used to create the newrelic.yml file that the Java agent uses to determine its configuration.

Role configuration variables

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 log files will live in a subdirectory of this directory.

jvm_conf_file

Required Path of the web server configuration file to reference the New Relic Java agent. For Tomcat, for instance, it's setenv.sh. If it doesn't exist, the file will be created.

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.

custom_instrumentation_files

Optional List of XML files to enable custom instrumentation by the Java agent. See the Custom instrumentation section for more details.

Agent configuration variables

Agent configuration goes in the nr_java_agent_config dictionary and is added to the Java agent's config file - newrelic.yml. The most common settings can be specified through this role. Examples can be found in examples/agent_install.yml.

To specify settings for specific hosts in your inventory use the nr_java_agent_host_config dictionary. For examples, see examples/inventory.yml. Host values override those in nr_java_agent_config.

If you need to configure settings that aren't listed below, you must provide your own, preconfigured newrelic.yml file (see Using your own agent config file).

license_key

Required Your New Relic license key.

app_name

Required Name of the application being instrumented. For more details, see the New Relic documentation on 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. For more details, see the New Relic documentation on configuring the Java agent.

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:

nr_java_agent_config:
  ...
  labels: Server:One;Data Center:Primary

collector_host

Optional If you need to specify a collector host, you can use the collector_host variable. See the New Relic documentation on collector endpoints for more details.

Other agent-specific configuration

Besides those listed above, you can configure the following settings through this Ansible role:

• agent_enabled
• high_security
• enable_auto_app_naming
• log_level
• audit_mode
• log_file_count
• log_limit_in_kbytes
• log_daily
• log_file_name
• log_file_path
• max_stack_trace_lines
• attributes: enabled, include, exclude
• transaction_tracer: enabled, transaction_threshold, record_sql, log_sql, stack_trace_threshold, explain_enabled, explain_threshold, top_n
• error_collector: enabled, ignore_errors, ignore_status_codes
• transaction_events: enabled, max_samples_stored
• distributed_tracing: enabled
• cross_application_tracer: enabled
• thread_profiler: enabled
• browser_monitoring: auto_instrument
• labels

See the Java agent configuration documentation for more details on these settings and others. If you need to configure settings besides these, you'll need to provide a fully-specified newrelic.yml. For details, see the Using your own agent config file section.

Using your own agent config file

If you need to specify agent configuration settings beyond those listed above, you'll need to provide your own newrelic.yml file. Any settings in the nr_java_agent_config dictionary will then be ignored. Set the variable nr_java_agent_config_file to the path to your file, for example:

nr_java_agent_config_file: /path/to/your/newrelic.yml

If this file is on the target hosts instead of on the system running Ansible, set nr_java_agent_config_file_is_remote to true:

nr_java_agent_config_file_is_remote: true

Example usage

The examples/agent_install.yml and examples/inventory.yml files provide an example of how to use the role.

After setting up your variables in examples/agent_install.yml and your inventory in examples/inventory.yml you can try the role by running Ansible:

ansible-playbook -i examples/inventory.yml examples/agent_install.yml

Custom instrumentation

If you want to enable custom instrumentation with XML, you can provide a list of XML files in the custom_instrumentation_files variable. These files will be copied to each host that the Java agent is being installed on, if you specify the variable in your playbook. You can also install different files to different hosts by specifying the variable at the host level in your inventory, or different files for different host groups by specifying the variable at the group level, either through your inventory or through files in the group_vars directory.

See the Ansible documentation on inventory and variables for more details on managing host and group variables. You can see some examples in this repo of how to specify custom instrumentation in the custom_instrumentation_playbook.yml and custom_instrumentation_inventory.yml files.

Development

Testing

This role uses molecule for testing. You'll need Docker and Python 3.6 or later. Install molecule with the docker module, if you haven't already:

$ pip install molecule[docker]

This will also install ansible, if necessary. To run the tests, call molecule test from the top level directory.

$ git clone https://github.com/newrelic/newrelic-java-agent-ansible-role
$ cd newrelic-java-agent-ansible-role
$ molecule test
--> Test matrix

└── default
    ├── dependency
    ├── lint
    ├── cleanup
...

Community

New Relic hosts and moderates an online forum where customers can interact with New Relic employees as well as other customers to get help and share best practices. Like all official New Relic open source projects, there's a related Community topic in the New Relic Explorers Hub. You can find the project's topic/threads here:

https://discuss.newrelic.com/t/ansible-role-for-new-relic-java-agent/99654

Issues / Enhancement Requests

Issues and enhancement requests can be submitted in the Issues tab of this repository. Please search for and review the existing open issues before submitting a new issue.

License

The project is released under version 2.0 of the Apache license.