Archival Notice

❗ Notice: This project has been archived as is and is no longer actively maintained.

The New Relic Java Ansible Role is archived because it is not used much. However, it can still be used in its current condition.

Ansible Role: New Relic Java Agent

This role installs and configures the New Relic Java agent. It works with little setup for applications on Tomcat, Jetty, or Wildfly. We plan to support popular Java web servers in the future.

• Requirements
• Installation
• Configuration
  • Role Configuration Variables
  • Agent Configuration Variables
  • Other Specific Agent Configuration
  • Using Your Own Agent Config File
• Example Usage
• Community
• Issues / Enhancement Requests
• License

Requirements

The unzip command must be available on the target machines.

Installation

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

$ ansible-galaxy install newrelic.new_relic_java_agent

If you want to make changes to the role, you can clone the repository and install it locally by running:

sh examples/install_role.sh

You might need to use sudo before the command, depending on how Ansible is installed on your system.

Configuration

This role uses variables for two main purposes: to configure the role and to configure the agent.

Role configuration variables help set up your hosts so that the agent files are installed correctly and your Java environment is configured.

Agent configuration variables can be defined globally in your playbook or for specific hosts or groups in your inventory file. They create the newrelic.yml file that the Java agent uses for its setup.

Role Configuration Variables

server_type

Required The web server used by your application. Possible options are: tomcat, jetty, and wildfly (in standalone mode).

server_root

Required The location of the web server on the host. The agent's files will be stored in a subdirectory of this directory.

jvm_conf_file

Required The path to the web server's config file to link to the New Relic Java agent. For Tomcat, it is setenv.sh. If it doesn't exist, this file will be created.

server_user / server_group

Required The user and group under which the web server operates. This is used to set the ownership of the newrelic.jar and newrelic.yml files.

restart_web_server

Optional - Default: true When set to false, the role will not restart the web server after installing the agent.

Remember, the agent won't work until the web server restarts.

service_name

Required (unless restart_web_server is false) The service name used to run the web server. It is utilized by Ansible to restart the web server after the agent installation.

custom_instrumentation_files

Optional A list of XML files for custom instrumentation by the Java agent. More details can be found in the Custom Instrumentation section.

Agent Configuration Variables

Configurations for the agent go into the nr_java_agent_config dictionary and are added to the agent's config file - newrelic.yml. Common settings can be defined through this role. Examples can be seen in examples/agent_install.yml.

To specify settings for specific hosts, use the nr_java_agent_host_config dictionary. Examples are available in examples/inventory.yml. Host settings override those in nr_java_agent_config.

If you need to configure settings not listed here, you must provide your own newrelic.yml file (see Using Your Own Agent Config File).

license_key

Required Your New Relic license key.

app_name

Required The name of the application being monitored. More details can be found in 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 through a proxy, use these values for proxy settings. More details can be found in the New Relic documentation.

labels

Optional Custom labels for the agent. Labels are name-value pairs, limited to 255 characters. Use semicolons (;) to separate 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, use the collector_host variable. More information is available in the New Relic documentation.

Other Specific Agent Configuration

Besides the above variables, you can set the following options 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

For more information on these settings, refer to the Java agent configuration documentation. If you need other settings, you will need to provide a complete newrelic.yml file (see Using Your Own Agent Config File).

Using Your Own Agent Config File

If you need settings not listed above, provide your newrelic.yml file. The settings in the nr_java_agent_config dictionary will be ignored. Set nr_java_agent_config_file to the path of your file, like this:

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

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

nr_java_agent_config_file_is_remote: true

Example Usage

The files examples/agent_install.yml and examples/inventory.yml show how to use the role.

After adjusting your variables in examples/agent_install.yml and your inventory in examples/inventory.yml, run Ansible with:

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

Custom Instrumentation

To enable custom instrumentation with XML, provide a list of XML files in the custom_instrumentation_files variable. These files will be copied to each host where the Java agent is installed if specified in your playbook. You can also install different files for different hosts by specifying the variable at the host level in your inventory or using group variables.

Refer to the Ansible documentation on inventory and variables for managing host and group variables. Examples can be found in the custom_instrumentation_playbook.yml and custom_instrumentation_inventory.yml files.

Development

Testing

This role uses Molecule for testing. Make sure you have Docker and Python version 3.6 or later. Install Molecule with the Docker module if you haven't done so:

$ pip install molecule[docker]

This will also install Ansible if needed. To run tests, use 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 has an online forum where users can connect with New Relic staff and other users for help and to share tips. Find the discussion for this project here:

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

Issues / Enhancement Requests

You can report issues and suggest improvements in the Issues tab of this repository. Please check existing issues before submitting a new one.

License

This project is licensed under version 2.0 of the Apache license.