newrelic_java_agent
Archival Notice
❗Notice: This project has been archived as is and is no longer actively maintained.
New Relic Java Ansible Role has been archived due to its low usage. It is still usable in its current state.
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
- 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.
ansible-galaxy install newrelic/newrelic-java-agent-ansible-role